Jenova Agent API-Referenz

Basis-URL: https://api.jenova.ai/v1

Authentifizierung: Bearer-Token in der Authorization-Kopfzeile

Inhaltsverzeichnis

• Überblick
• Schnellstart
• Kernkonzepte
• Authentifizierung
• API-Endpunkte
  • Nachrichten
  • Sitzungen
  • Vorgänge
  • Guthaben
  • Agents
  • Modelle
  • Dokumentation
• Datenstromübertragung (SSE)
• MCP-Server-Integration
• Abrechnung
• Ratenbegrenzungen
• Fehlerbehandlung
• Paginierung
• Lokalisierung
• Datenschutz und Daten
• Kundensupport

Überblick

Erstellen und betreiben Sie produktionsreife AI-Agenten, ohne den zugrundeliegenden Stack selbst zusammenstellen zu müssen. Die Jenova Agent API vereint alle zentralen Fähigkeiten in einem einzigen verwalteten Dienst:

Der vollständige Agent-Stack

• Agent-Orchestrierung: Eine einheitliche Orchestrierungsschicht koordiniert Modelle, Werkzeuge, Speicher und Retrieval über komplexe Workflows hinweg.
• Speicher & Kontext: Unbegrenzter Gesprächsspeicher und Kontext, integriert in jede Sitzung. Keine externe Zustandsverwaltung erforderlich.
• Werkzeuge & MCP: Unbegrenzte Werkzeugintegrationen mit plattformeigenen Werkzeugen und jedem beliebigen entfernten MCP-Server, sofort einsatzbereit.
• Beliebiges Modell verwenden: Betreiben Sie Ihre Agents mit Modellen von OpenAI, Anthropic, Google, xAI, Qwen und weiteren über eine einzige Integration.
• Vollständig verwalteter Speicher: Verwaltete relationale und Vektordatenbanken mit integriertem RAG. Keine Infrastruktur, die bereitgestellt oder skaliert werden muss.
• Produktionsreif: Wird von Hunderttausenden von Nutzern verwendet. Vollständig verwaltete Infrastruktur, stabile APIs, für Produktionsverkehr ausgelegt.

Schnellstart

1. Ihren API-Schlüssel erhalten

Generieren Sie einen API-Schlüssel im Entwickler-Dashboard unter www.jenova.ai/platform. Schlüssel verwenden das Format jnv_sk_* und werden als Bearer-Tokens übergeben.

2. Einen Agent auswählen oder erstellen

Wählen Sie einen vorgefertigten Agent von der Plattform aus oder erstellen Sie im Dashboard einen benutzerdefinierten Agent mit Anweisungen, Modelleinstellungen, Wissensdatenbank-Dateien, Werkzeugen und MCP-Servern.

3. Ihre erste Nachricht senden

Erstellen Sie eine Sitzung und senden Sie eine Nachricht in einem einzigen Aufruf:

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

Die Antwort wird als Server-Sent Events zurückgestreamt:

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

Erfassen Sie session_id aus stream_started für Folgeanfragen. Für synchrone JSON-Antworten siehe Nachricht senden.

Kernkonzepte

Agent

Ein AI-Agent, mit dem Sie über die API interagieren. Jeder Agent hat einen eindeutigen Slug (z. B. my-support-agent), der als agent-Wert in API-Aufrufen verwendet wird.

• Vorgefertigt: Wählen Sie aus vorhandenen Agents auf der Plattform.
• Benutzerdefiniert: Konfigurieren Sie Ihren eigenen im Dashboard mit Anweisungen, Modell, Wissensdatenbank, Werkzeugen und MCP-Servern.

Sitzung

Ein eigenständiger Gesprächsverlauf zwischen einem Endbenutzer und einem Agent.

• Kennung: ID mit Präfix (z. B. ses_abc123)
• Geltungsbereich: Für denselben Agent und Endbenutzer können mehrere Sitzungen existieren, jede mit eigenständigem Gesprächszustand
• Lebenszyklus: Sitzungen bleiben unbegrenzt erhalten, bis sie über die API gelöscht werden. Für speicherlose Einmalaufgaben verwenden Sie POST /messages mit ephemeral: true
• Plattformisolierung: API-Sitzungen sind getrennt von Gesprächen in der Jenova-Webanwendung. Endbenutzer, Sitzungsverlauf und Abrechnung sind zwischen der API und der Webanwendung unabhängig voneinander.

Nachricht

Ein einzelner Eintrag im Gesprächsverlauf einer Sitzung, der von den Nachrichten-Endpunkten zurückgegeben wird. Jede Nachricht enthält ein strukturiertes from-Objekt mit type ("user" oder "agent") und name, sowie einen Nachrichten-type:

• external – eine Gesprächsnachricht, die als Chat-Inhalt angezeigt werden soll.
• internal – eine optionale Nachricht, die Arbeitsschritte des Agents während einer Ausführung darstellt, wie Werkzeugaufrufe oder Retrieval.

Ausführung

Eine einzelne Agent-Ausführung, die erstellt wird, wenn Sie eine Nachricht senden. Eine Ausführung hat eine run_id, kann während ihrer aktiven Phase Ereignisse streamen und erzeugt eine oder mehrere abgeschlossene Nachrichten. Jede Sitzung kann jeweils nur eine aktive Ausführung haben.

Endbenutzer

Das Feld user grenzt Sitzungen auf einen Endbenutzer in Ihrer Anwendung ein. Verwenden Sie eine stabile, undurchsichtige ID, wie z. B. Ihre interne Benutzer-ID oder UUID. Vermeiden Sie E-Mail-Adressen oder andere personenbezogene Daten, sofern Ihre Anwendung dies nicht erfordert. Sitzungen, die mit demselben user-Wert erstellt wurden, werden gruppiert, was eine Auflistung von Sitzungen pro Benutzer ermöglicht.

Wenn user weggelassen wird, ist die Sitzung Ihrem Entwicklerkonto zugeordnet und kann später nicht nach Endbenutzer gefiltert werden. Übergeben Sie user im Produktionsbetrieb.

Bei Anfragen zu bestehenden Sitzungen ist user eine optionale Besitzprüfung. Wenn Sie es angeben, muss es mit dem user-Wert übereinstimmen, der bei der Erstellung der Sitzung verwendet wurde; andernfalls gibt die API 404 session_not_owned zurück. Senden Sie es als Abfrageparameter bei GET- und DELETE-Anfragen und im JSON-Text bei POST- und PATCH-Anfragen.

Authentifizierung

Authentifizieren Sie jede Anfrage mit einem Bearer-Token in der Authorization-Kopfzeile:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API-Schlüssel werden über das Entwickler-Dashboard erstellt.

User-Agent ist optional. SDKs können diesen Wert zu Diagnosezwecken setzen, die API erfordert ihn jedoch nicht.

Schlüsselformat: Schlüssel beginnen mit dem Präfix jnv_sk_, gefolgt von einer base62-codierten Zufallszeichenfolge.

Limits: Jedes Entwicklerkonto kann bis zu 10 aktive API-Schlüssel haben.

API-Endpunkte

Nachrichten

Das Senden von Nachrichten ist der primäre API-Pfad. Verwenden Sie POST /messages für die erste Nachricht; dadurch wird die Sitzung erstellt und die Ausführung in einer einzigen Anfrage gestartet. Verwenden Sie POST /sessions/{session_id}/messages, um eine bereits erfasste session_id fortzusetzen.

Nachricht senden

POST /messages

Erstellt eine dauerhafte Sitzung und sendet die erste Nachricht in einer atomaren Anfrage. Setzen Sie ephemeral: true für eine speicherlose, ausschließlich per Datenstromübertragung erfolgende Einmalanfrage, die weder Sitzung noch Nachrichtenverlauf speichert, keine Sitzungs-ID zurückgibt und nicht fortgesetzt werden kann.

Anfragetext

Beispiel – Datenstromübertragung (Standard)

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

Die Antwort ist ein SSE-Datenstrom (Ereignisformat siehe Datenstromübertragung (SSE)). Bei dauerhaften Anfragen enthält die Antwort die neue session_id; bei Anfragen mit ephemeral: true fehlt session_id, und diese müssen per Datenstromübertragung erfolgen.

Beispiel – JSON (ohne Datenstromübertragung)

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

Antwort

Antworten mit Datenstromübertragung geben die in Datenstromübertragung (SSE) dokumentierten SSE-Ereignisse aus. Antworten ohne Datenstromübertragung geben die in Sitzung fortsetzen gezeigte JSON-Nachrichtenstruktur zurück, einschließlich stop_reason und usage für die abgeschlossene Anfrage.

Wird eine Ausführung ohne Datenstromübertragung nach 90 Sekunden noch verarbeitet, gibt die API 202 Accepted mit status: "processing", session_id, run_id und message zurück. Die Ausführung wird nach der Antwort oder einer Client-Trennung fortgesetzt; prüfen Sie die Nachrichten der Sitzung, oder verwenden Sie Datenstromübertragung für längere Arbeitsabläufe.

Fehler

Sitzung fortsetzen

POST /sessions/{session_id}/messages

Sendet eine Nachricht an eine bestehende persistente Sitzung und empfängt die Antwort des Agents. Antworten werden standardmäßig per SSE gestreamt; setzen Sie stream: false für JSON.

Anfragetext

Beispiel - Datenstromübertragung (Standard)

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

Beispiel - JSON (ohne Datenstromübertragung)

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

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

Wenn die Sitzung bereits eine aktive Ausführung oder wartende Nachrichten hat, gibt die API JSON 202 Accepted mit status: "queued", session_id, run_id und message_id zurück. Die Nachricht des Benutzers wird von der aktiven Ausführung verarbeitet.

Fehler

Idempotenz

POST /messages und POST /sessions/{session_id}/messages akzeptieren eine optionale Idempotency-Key-Kopfzeile. Verwenden Sie für jeden logischen Sendevorgang eines Benutzers einen eindeutigen Schlüssel, damit Netzwerkwiederholungen oder doppelte Übermittlungen keine doppelten Ausführungen erzeugen.

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

Ohne Datenstromübertragung: Eine Wiederholung gibt die gespeicherte 200- oder 202-Antwort mit der Kopfzeile Idempotent-Replayed: true zurück.

Mit Datenstromübertragung: Der Datenstrom wird nicht erneut abgespielt. Eine Wiederholung während der Ausführung oder nach deren Abschluss gibt einen Idempotenzfehler mit der ursprünglichen run_id und, bei persistenten Anfragen, der session_id zurück. Verwenden Sie GET /sessions/{session_id}/runs/{run_id}, um eine aktive Ausführung zu prüfen, oder GET /sessions/{session_id}/messages, um persistierte Ergebnisse abzurufen.

Beispiel für eine Wiederholung nach abgeschlossener Datenstromübertragung:

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

Idempotenzfehler

Nachrichten auflisten

GET /sessions/{session_id}/messages

Gibt eine paginierte Liste sichtbarer Konversationsnachrichten zurück. Die erste Seite enthält die aktuellsten Nachrichten; innerhalb jeder Seite sind die Nachrichten chronologisch geordnet (älteste zuerst). sequence ist eine stabile Ordnungsnummer innerhalb der Sitzung.

Abfrageparameter

Beispiel

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

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

Message-Objekt

File-Objekt

Fehler

Nachricht abrufen

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

Ruft eine einzelne sichtbare Nachricht anhand ihrer ID ab.

Antwort 200 OK

Gibt ein einzelnes Message-Objekt mit derselben Struktur wie die Listenantwort zurück.

Fehler

Dateianhänge

Übergeben Sie öffentlich zugängliche HTTPS-URLs im Feld file_urls.

Unterstützte Formate

• Bilder: JPG, JPEG, PNG, WebP
• Dokumente: 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

Beim Auflisten von Nachrichten erscheinen angehängte Dateien im files-Array der Nachricht.

Sitzungen

Sitzungen sind dauerhafte Konversationen zwischen einem Endbenutzer und einem Agent. Die meisten Integrationen können sie implizit mit POST /messages erstellen.

Sitzung erstellen

POST /sessions

Erstellt eine leere persistente Sitzung, die an einen bestimmten Agent gebunden ist. Verwenden Sie dies, wenn Sie eine Sitzungs-ID benötigen, bevor die erste Nachricht gesendet wird; andernfalls empfiehlt sich POST /messages.

Hinweis: ephemeral wird bei POST /sessions nicht akzeptiert; verwenden Sie für einmalige Anfragen ohne Speicherung POST /messages mit ephemeral: true.

Anfragetext

Beispiel

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

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

Fehler

Sitzungen auflisten

GET /sessions

Gibt eine paginierte Liste Ihrer Sitzungen zurück, sortiert nach der zuletzt aktualisierten.

Abfrageparameter

Beispiel

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

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

Fehler

Sitzung abrufen

GET /sessions/{session_id}

Ruft eine einzelne Sitzung anhand ihrer ID ab.

Antwort 200 OK

Gibt ein Sitzungsobjekt mit derselben Struktur wie die Antwort bei der Erstellung zurück.

Fehler

Sitzung umbenennen

PATCH /sessions/{session_id}

Aktualisiert den Anzeigenamen einer Sitzung.

Anfragetext

Antwort 200 OK

Gibt das aktualisierte Sitzungsobjekt zurück.

Fehler

Sitzung löschen

DELETE /sessions/{session_id}

Löscht eine Sitzung und alle ihre Nachrichten dauerhaft. Die Sitzung darf keine aktive Ausführung haben.

Antwort 204 No Content

Fehler

Vorgänge

Diese Endpunkte sind Wiederherstellungs- und Bearbeitungssteuerungen für persistente Sitzungen. Die meisten Integrationen benötigen nur „Abbrechen“; verwenden Sie die anderen Vorgänge, wenn Sie den Sitzungsstatus absichtlich ändern oder wiederherstellen möchten. Alle Vorgänge unterstützen den optionalen user-Besitzschutz, der unter Endbenutzer beschrieben wird.

Aktive Ausführung abbrechen

POST /sessions/{session_id}/cancel

Bricht die aktuell laufende Agent-Ausführung ab. Dabei werden Nachrichten, die vor dem Abbruch bereits abgeschlossen wurden, nicht gelöscht.

Anfragetext

Antwort 204 No Content

Fehler

Aktive Ausführung rückgängig machen

POST /sessions/{session_id}/undo

Bricht die aktive Ausführung ab, wartet, bis sie gestoppt ist, und entfernt anschließend alle Nachrichten, die sie bereits hinzugefügt hat. Nach dem Auslösen des Rückgängig-Vorgangs wird keine weitere Ausgabe gespeichert.

Anfragetext

Antwort 200 OK

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

Wird die Ausführung abgebrochen, bevor eine Nachricht abgeschlossen wurde, ist deleted ein leeres Array.

Fehler

Letzte Nachrichten löschen

POST /sessions/{session_id}/messages/delete

Entfernt die N zuletzt gesendeten Nachrichten aus einer inaktiven Sitzung. Die Sitzung darf keine aktive Ausführung haben.

Anfragetext

Antwort 200 OK

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

Fehler

Sitzung verzweigen

POST /sessions/{session_id}/fork

Erstellt eine neue Sitzung, indem die Quellsitzung bis zu einer bestimmten Nachricht kopiert wird. Die Quellsitzung darf keine aktive Ausführung haben.

Anfragetext

Antwort 201 Created

Gibt das neu erstellte Sitzungsobjekt mit derselben Struktur wie bei der Sitzungserstellung zurück.

Fehler

Ausführungsstatus abrufen

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

Gibt den aktuellen Status einer aktiven Ausführung zurück. Verwenden Sie dies nach einer unterbrochenen SSE-Verbindung oder einer Idempotenzantwort, die eine run_id zurückgegeben hat. Sobald eine Ausführung abgeschlossen ist, rufen Sie die Ergebnisse mit GET /sessions/{session_id}/messages ab.

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

Die Antwort kann außerdem Hinweise zum aktuellen Fortschritt enthalten, während die Ausführung aktiv ist.

Fehler

Guthaben

Kontostand abrufen

GET /credits/balance

Gibt Ihren aktuellen Guthabenstand zurück.

Antwort 200 OK

{
  "balance": "123.45"
}

Agents

Erstellen und bearbeiten Sie benutzerdefinierte Agents im Dashboard. API-Unterstützung für das Erstellen und Bearbeiten von Agents folgt in Kürze.

Geplante/Hintergrund-Workflows werden derzeit über die API nicht unterstützt. Diese Unterstützung folgt in Kürze.

Agents auflisten

GET /agents

Gibt die für Ihren API-Schlüssel verfügbaren Agents zurück. Verwenden Sie den Wert agent, wenn Sie Sitzungen erstellen oder Nachrichten senden.

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

Modelle

Modelle auflisten

GET /models

Gibt alle Modelle zurück, die im Feld model beim Senden von Nachrichten verwendet werden können.

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

Modelle mit einer thinking_variant unterstützen erweitertes Reasoning. Verwenden Sie die Varianten-ID direkt im Feld model, um es zu aktivieren.

Wird beim Senden einer Nachricht kein model angegeben, wird das Standardmodell des Agents verwendet.

Dokumentation

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

Gibt diese Referenz als Markdown zurück. Verwenden Sie lang, um die Sprache auszuwählen.

Datenstromübertragung (SSE)

Wenn stream weggelassen wird oder true ist (Standard), werden Nachrichtenantworten als Server-Sent Events übermittelt. Verwenden Sie message_completed-Ereignisse, um Nachrichten zu identifizieren, die abrufbereit oder renderbereit sind.

Zeitüberschreitung: SSE-Verbindungen bleiben bis zu 60 Minuten offen. Nicht-streamende Anfragen warten bis zu 90 Sekunden und geben dann 202 Accepted zurück, während die Ausführung fortgesetzt wird.

Verbindungs-Kopfzeilen

Die SSE-Antwort setzt diese Kopfzeilen:

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

X-Run-Id ist bereits vor dem ersten SSE-Ereignis verfügbar.

Wiederverbindung und Wiederherstellung

SSE-Datenströme werden nicht erneut abgespielt. Wenn die Verbindung abbricht, verwenden Sie die erfasste session_id und run_id, um den Zustand wiederherzustellen:

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

Ist die Ausführung noch aktiv, liefert dies den aktuellen Status, den bisherigen Teiltext und den letzten Fortschritt. Wird 404 not_found zurückgegeben, ist die Ausführung nicht mehr aktiv; rufen Sie die Nachrichten der Sitzung ab, um die abgeschlossene Ausgabe abzugleichen:

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

Frame-Format

Jeder SSE-Frame folgt dem Standardformat:

event: <event_type>
data: <json_payload>

Zwei Zeilenumbrüche beenden jeden Frame.

Ereignistypen

Datenströme enthalten Lebenszyklus-, Text-Delta-, Denk-, Fortschritts-, Warn-, Nachrichtenabschluss-, MCP-Verbindungs-, Fehler-, Abschluss- und Ping-Ereignisse. Manche Ereignistypen werden nur gesendet, wenn sie relevant sind.

Bei ephemeren Anfragen (ephemeral: true) lässt jedes SSE-Ereignis session_id aus. Verwenden Sie ausschließlich run_id, um Ereignisse innerhalb dieses einen Datenstroms zu korrelieren.

Für die abschließende Abstimmung bei persistenten Anfragen warten Sie auf stream_ended und rufen dann „List Messages“ auf.

Gemeinsame Felder bei ausführungsbezogenen Ereignissen:

stream_started

Wird einmal gesendet, wenn die Ausführung beginnt.

stream_delta

Wird wiederholt gesendet, während der Agent sichtbaren Antworttext erzeugt. Verketten Sie die chunk_content-Werte in der Reihenfolge von seq, um die per Datenstromübertragung übertragene Antwort zusammenzusetzen.

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

stream_thinking

Wird wiederholt gesendet, während der Agent Denkausgaben erzeugt. Verwenden Sie dies für eine separate Denkanzeige oder Ablaufverfolgung; fügen Sie es nicht dem endgültigen Antworttext hinzu.

stream_progress

Meldet für den Benutzer sichtbare Aktivitäten während der Generierung, etwa das Lesen eines Dokuments, die Websuche oder das Warten auf eine Benutzeraktion. Diese Ereignisse sind für eine vorübergehende UI-Anzeige gedacht; ignorieren Sie unbekannte Felder. Verwenden Sie abgeschlossene Nachrichten als maßgebliche Nachrichtenhistorie.

Erweitert: Nachrichtenanfragen akzeptieren include_progress: false, um ausschließlich stream_progress auszulassen. Lebenszyklus-Ereignisse, ping, message_completed, Fehler und abschließende Ereignisse werden weiterhin gesendet, wenn sie relevant sind.

Manche Fortschrittsereignisse können url, file_name oder server_name als optionale Anzeigehinweise enthalten.

message_completed

Wird jedes Mal gesendet, wenn eine Nachricht vollständig ist und abgerufen oder dargestellt werden kann.

Dies ist eine Grenzmarkierung, kein vollständiges Nachrichtenobjekt. Rufen Sie die Nachricht ab, wenn Sie Inhalt oder Metadaten benötigen.

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

Wird gesendet, wenn der Agent den Endbenutzer benötigt, um einen oder mehrere MCP-Server zu verbinden oder zu autorisieren, bevor er fortfahren kann. Dieses Ereignis ist nur im Streaming-Modus verfügbar.

mcp_connection_resolved

Wird gesendet, wenn die MCP-Verbindungsaktion des Benutzers abgeschlossen wurde oder abgelaufen ist.

Keine zusätzlichen Felder über die gemeinsamen ausführungsbezogenen Felder hinaus.

warning

Wird bei nicht fatalen Warnungen während einer Ausführung gesendet.

stream_error

Wird gesendet, wenn eine Ausführung fehlschlägt. Anschließend kann ein abschließendes stream_ended-Ereignis mit success:false und stop_reason:"error" folgen.

stream_ended

Wird einmalig gesendet, wenn die Ausführung beendet ist. Dies ist das letzte Ereignis des Datenstroms.

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

Beispiel für einen Fehlschlag:

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

ping

Keepalive-Frames, die alle 15 Sekunden gesendet werden, um Zeitüberschreitungen bei Proxys/CDNs zu verhindern. Ignorieren Sie diese in Ihrem Client.

MCP-Server-Integration

Verbinden Sie Ihre Agents über das Model Context Protocol (MCP) mit externen Werkzeugen:

• Von Jenova verwaltete MCP-Server: Von Jenova gehostete Server für Suche, Inhaltsabruf, Dokumentenerstellung und weitere integrierte Funktionen
• Externe MCP-Server: Andere externe MCP-Server, die für Ihren Agent konfiguriert sind

MCP-Server müssen im Dashboard beim Erstellen oder Bearbeiten Ihres Agents konfiguriert werden. Um einen eigenen MCP-Server zu verwenden, fügen Sie ihn einem benutzerdefinierten Agent hinzu und rufen diesen Agent anschließend über die API auf. Die API führt die im Agent konfigurierten Werkzeuge aus; in den API-Anfragen selbst ist keine zusätzliche Einrichtung erforderlich.

Wenn ein Agent während einer Antwort MCP-Werkzeuge verwendet, werden entsprechende Fortschritts-Ereignisse fortlaufend im Datenstrom gesendet:

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

Wenn der Agent während der Ausführung eine Verbindung oder Autorisierung eines MCP-Servers durch den Endbenutzer benötigt, können die Streaming-Antworten die Ereignisse mcp_connection und mcp_connection_resolved enthalten. Zeigen Sie Ihrem Endbenutzer die Serverliste für die Verbindung an und öffnen Sie, sofern vorhanden, die angegebene auth_url. Halten Sie den SSE-Stream geöffnet, während der Benutzer den Server verbindet oder autorisiert.

Nach der Autorisierung speichert Jenova das Token, das Autorisierungsfenster zeigt eine Abschlussseite an, und dieselbe Ausführung wird automatisch fortgesetzt. Der Endbenutzer muss die Nachricht nicht erneut senden.

Wenn der Endbenutzer vor user_action_deadline_unix weder verbindet, autorisiert, überspringt noch stummschaltet, endet die Ausführung mit stop_reason:"user_action_timeout". Sie können die aktive Ausführung auch mit POST /sessions/{session_id}/cancel abbrechen.

Speichern Sie die auth_url clientseitig. Falls der Client während der Autorisierung die Verbindung verliert, bleibt die URL bis user_action_deadline_unix gültig. Für dauerhafte Anfragen stellen Sie die Verbindung mit „Ausführungsstatus abrufen“ wieder her oder rufen die Nachrichten nach Abschluss der Ausführung ab.

Nicht-Streaming-Anfragen (stream: false) unterstützen keine MCP-Verbindungsaktionen für Benutzer; verwenden Sie für Agents, die diese Interaktion möglicherweise benötigen, Streaming.

MCP-Verbindung überspringen

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

Verwirft eine ausstehende MCP-Verbindungsaktion und lässt die Ausführung ohne diese Verbindung fortsetzen.

Um zukünftige Verbindungsaufforderungen für einen Server für denselben API-Benutzer stummzuschalten, geben Sie mcp_server_id und mute an. Unterstützte Werte sind 24h und forever.

Anfragetext

Antwort 204 No Content

Der Stream sendet mcp_connection_resolved, anschließend wird die Ausführung mit derselben run_id fortgesetzt.

Fehler

Abrechnung

Alle Kosten werden von Ihrem Entwickler-Guthaben abgezogen. Nutzung anzeigen und Guthaben aufladen können Sie unter www.jenova.ai/platform.

Preise

Die Kosten einer Nachricht hängen ab von:

• Modell – unterschiedliche Modelle haben unterschiedliche Kosten pro Token
• Kontextlänge – längere Sitzungen verbrauchen mehr Input-Token pro Anfrage
• Workflow-Komplexität – längere Workflows und intensivere Werkzeugnutzung (Websuche, Dateierstellung, Dokumentenanalyse) erhöhen den gesamten Token-Verbrauch

Die tatsächlichen Kosten werden bei Streaming-Anfragen als stream_ended.usage.cost und bei nicht-Streaming-JSON-Anfragen als usage.cost zurückgegeben.

Guthabenreservierungen

Für jede neue Nachrichten-Ausführung wird vor Beginn der Ausführung eine Guthabenreservierung von $0,50 auf Ihr Guthaben gelegt. Damit werden Mittel für die Ausführung reserviert. Nachrichten, die während einer aktiven Ausführung in die Warteschlange eingereiht werden, erzeugen keine zusätzliche Reservierung; die Nutzung der aktiven Ausführung wird gegen Ihr verbleibendes Guthaben geprüft.

Nach Abschluss der Ausführung wird die Reservierung auf die tatsächlichen Kosten abgerechnet und die Differenz freigegeben. Bei abgebrochenen und fehlgeschlagenen Ausführungen wird nur die bereits entstandene Nutzung berechnet. Schlägt eine Anfrage fehl, bevor sie das Modell erreicht, wird die vollständige Reservierung freigegeben.

Das bedeutet, dass Ihr verfügbares Guthaben während laufender Anfragen vorübergehend niedriger erscheinen kann. Sie benötigen mindestens $0,50 verfügbares Guthaben, um eine Nachricht an eine bestehende Sitzung oder eine flüchtige Nachricht zu senden. Eine erste dauerhafte POST /messages-Anfrage erstellt eine Sitzung und erfordert mindestens $0,51, um sowohl die Reservierung für die Nachricht als auch die Gebühr für die Sitzungserstellung abzudecken.

Ratenbegrenzungen

Jedes Entwicklerkonto unterliegt drei Dimensionen der Ratenbegrenzung:

GET- und HEAD-Anfragen belegen keine Slots für gleichzeitige Anfragen. cancel, undo und mcp/connection/skip belegen ebenfalls keine solchen Slots, sodass diese Vorgänge auch dann verfügbar bleiben, wenn alle Slots belegt sind. Diese Anfragen zählen jedoch weiterhin für RPM und RPD.

Antwort-Kopfzeilen

Authentifizierte API-Antworten enthalten Ratenbegrenzungs-Kopfzeilen:

Wenn ein Limit überschritten wird, gibt die API 429 Too Many Requests zurück:

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

Fehlerbehandlung

Unmittelbare HTTP-Fehler und Nicht-Streaming-Ausführungsfehler folgen einem einheitlichen Format:

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

Fehlermeldungen werden basierend auf dem Parameter lang lokalisiert (siehe Lokalisierung).

Streaming-Ausführungsfehler werden als stream_error-Ereignisse übermittelt. Eine fehlgeschlagene Ausführung kann trotzdem ein abschließendes stream_ended-Ereignis mit success:false und gesetztem stop_reason senden. Nicht-Streaming-Ausführungsfehler können zudem ein usage-Objekt auf oberster Ebene enthalten, sofern Kostendaten verfügbar sind.

Endpunktspezifische Fehler sind direkt bei den jeweiligen Endpunkten dokumentiert.

Ausführungsfehler nach dem Start

Ausführungsfehler treten auf, nachdem eine Nachrichten-Ausführung bereits gestartet wurde. Im Streaming-Modus erscheinen sie als stream_error-Ereignisse und können von stream_ended mit success:false gefolgt werden. Im Nicht-Streaming-Modus werden sie als JSON-Fehlerantwort mit dem unten angegebenen HTTP-Statuscode zurückgegeben.

Paginierung

Listen-Endpunkte verwenden eine cursorbasierte Paginierung:

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

Übergeben Sie next_cursor als Abfrageparameter cursor, um die nächste Seite abzurufen. Wenn has_more den Wert false hat, gibt es keine weiteren Ergebnisse.

Lokalisierung

Alle Endpunkte akzeptieren einen optionalen Abfrageparameter lang, um die Sprache von Fehlermeldungen und anderen lokalisierten Inhalten zu steuern.

Sie können ?lang=xx an jede Anfrage-URL anhängen:

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

Unterstützte Sprachen: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Datenschutz und Daten

Jenova verwendet API-Prompts, Ausgaben, Konversationsverläufe, hochgeladene Dateien, Agentenanweisungen oder Wissensdatenbanken nicht, um Jenova-Modelle zu trainieren.

Bei Modellanbietern von Drittanbietern nutzt Jenova kommerzielle API-Kanäle, Kontoeinstellungen, vertragliche Zusicherungen oder Opt-outs, die darauf ausgelegt sind, zu verhindern, dass Kundeninhalte zum Training von Anbietermodellen verwendet werden.

Jenova speichert und verarbeitet API-Daten unter Verwendung von US-Infrastruktur. Drittanbieter können Daten in anderen Rechtsordnungen verarbeiten, wie in der Datenschutzerklärung und den Nutzungsbedingungen beschrieben.

Weitere Einzelheiten finden Sie in den Nutzungsbedingungen, der Datenschutzerklärung und der Nutzungsrichtlinie.

Kundensupport

• Dashboard: www.jenova.ai/platform
• E-Mail: [email protected]