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

Betreiben Sie in wenigen Minuten maßgeschneiderte Agenten in Ihrem Produkt oder Workflow. Richten Sie Ihre Agenten für jede Aufgabe ein, wählen Sie Modell und Tools Ihrer Wahl und überlassen Sie Jenova den Agent-Harness, die Datenbank und die Skalierung.

Der vollständige Agent-Stack:

• Verwalteter Agent-Harness: Ein Aufruf geht hinein, fertige Arbeit kommt heraus. Ihr Agent recherchiert, denkt nach, ruft Tools auf und erzeugt die Dateien – exakt nach Ihren Anweisungen.
• Unbegrenzter Kontext und Gedächtnis: RAG-gestütztes Kontextmanagement und proprietäres Session-State-Tracking ermöglichen unbegrenztes Gedächtnis innerhalb eines Gesprächs.
• Bibliothek aus Tools und MCP: Verbinden Sie sich mit unserer Bibliothek aus 30+ Tools und MCP-Servern – etwa Suche, Bildgenerierung, E-Mail und mehr – oder binden Sie Ihre eigenen MCP-Server an.
• Nahtloser Wechsel zu jedem Modell: Deployen Sie Modelle von OpenAI, Anthropic, Google, xAI oder führenden Open-Source-Anbietern und wechseln Sie mit einem einzigen Parameter zwischen den Modellen.
• Verwaltetes Wissen & RAG: Jenova übernimmt die End-to-End-RAG-Pipeline – Chunking, Indexierung, Speicherung und Retrieval.
• Im großen Maßstab erprobt: Deployen Sie auf kampferprobter Infrastruktur, auf der Hunderte Agenten im Produktivbetrieb laufen. Null Cluster, die Sie provisionieren, skalieren oder warten müssen.

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 Einmalaufgaben, die keine Sitzung benötigen, 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 eine oder mehrere abgeschlossene Nachrichten erzeugen. 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 einer bestehenden Sitzung (jeder Endpunkt mit {session_id} im Pfad) 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. Ein user-Abfrageparameter bei POST oder PATCH gibt 400 bad_request zurück.

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 einzigen Anfrage. Setzen Sie ephemeral: true für eine ausschließlich per Datenstromübertragung erfolgende Einmalanfrage, die keine Sitzungs-ID zurückgibt und nicht fortgesetzt werden kann. Ihre Daten werden kurz nach Abschluss der Anfrage gelöscht.

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 das Nachrichtenobjekt mit stop_reason und usage für die Anfrage zurück, wie in Sitzung fortsetzen gezeigt. stop_reason ist end_run, oder user_cancelled, wenn die Ausführung abgebrochen wurde, nachdem der Agent eine Nachricht erzeugt hatte.

Wird die Ausführung abgebrochen, bevor der Agent eine Nachricht erzeugt, gibt die API 200 OK mit status: "cancelled", session_id, run_id, stop_reason: "user_cancelled" und usage zurück.

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 einer menschenlesbaren 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. Anfragen mit additional_context geben stattdessen 409 busy zurück.

Antworten ohne Datenstromübertragung folgen denselben Regeln wie bei Nachricht senden, einschließlich der Antwort status: "cancelled", wenn die Ausführung abgebrochen wird, bevor der Agent eine Nachricht erzeugt.

Fehler

Idempotenz

POST /messages, POST /sessions/{session_id}/messages und POST /invoke akzeptieren eine optionale Idempotency-Key-Kopfzeile (max. 255 Zeichen). Verwenden Sie für jeden logischen Sendevorgang eines Benutzers einen eindeutigen Schlüssel, damit Netzwerkwiederholungen oder doppelte Übermittlungen keine doppelten Ausführungen erzeugen. Schlüssel werden 24 Stunden lang aufbewahrt.

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 Antwort mit der Kopfzeile Idempotent-Replayed: true zurück, einschließlich Fehlern, die nach Beginn der Verarbeitung der Anfrage zurückgegeben wurden. Eine gespeicherte 202 Accepted-Antwort wird unverändert erneut zurückgegeben; verwenden Sie Ausführungsstatus abrufen oder Nachrichten auflisten, um das Ergebnis zu prüfen. Anfragen, die vor Beginn der Verarbeitung abgelehnt werden, etwa wegen Validierungs- oder Guthabenfehlern, werden nicht gespeichert, sodass eine Wiederholung erneut ausgewertet wird.

Mit Datenstromübertragung: Der Datenstrom wird nicht erneut abgespielt. Bei POST /messages und POST /sessions/{session_id}/messages gibt eine Wiederholung während der Ausführung oder nach deren Abschluss einen Idempotenzfehler mit der ursprünglichen run_id und, bei persistenten Anfragen, der session_id zurück. Verwenden Sie bei persistenten Anfragen Ausführungsstatus abrufen, um eine aktive Ausführung zu prüfen, oder Nachrichten auflisten, um persistierte Ergebnisse abzurufen. Ergebnisse von POST /invoke mit Datenstromübertragung können nach dem Schließen des Datenstroms nicht abgerufen werden. Wiederholungen von POST /invoke geben die ursprüngliche id statt run_id und session_id zurück.

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 der Nachrichten der Sitzung zurück. Standardmäßig werden nur external-Konversationsnachrichten zurückgegeben. Die erste Seite enthält die aktuellsten Nachrichten; innerhalb jeder Seite sind die Nachrichten chronologisch geordnet (älteste zuerst). sequence ist die Ordnungsnummer der Nachricht 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",
      "stop_reason": "end_run"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Message-Objekt

File-Objekt

Fehler

Nachricht abrufen

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

Ruft eine einzelne Nachricht anhand ihrer ID ab.

Abfrageparameter

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

Datei-URLs werden abgerufen, wenn der Agent sie während der Ausführung liest, nicht wenn die Anfrage angenommen wird. Eine URL, die nicht abgerufen werden kann, oder eine Datei über 20 MB wird nicht gelesen; die Anfrage selbst wird nicht abgelehnt.

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

Zusätzlicher Kontext

Übergeben Sie benannten Kontext für eine einzelne Nachricht in additional_context, etwa Details zum Konto des Endbenutzers. Er wird nicht im Nachrichtenverlauf gespeichert.

Verwenden Sie einen aussagekräftigen Namen wie customer_profile oder order_details.

Ein Eintrag, bei dem name oder content fehlt oder kein String ist, gibt 400 invalid_payload zurück. Andere ungültige Einträge geben 400 bad_request zurück.

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

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

Sitzungsobjekt

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

Fehler

Sitzung abrufen

GET /sessions/{session_id}

Ruft eine einzelne Sitzung anhand ihrer ID ab.

Abfrageparameter

Antwort 200 OK

Gibt ein Sitzungsobjekt 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 Aktive Ausführung 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 aktive 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 count zuletzt gesendeten Nachrichten aus einer inaktiven Sitzung, einschließlich internal-Nachrichten. Verwenden Sie include=all bei Nachrichten auflisten, um sie anzuzeigen. 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 (optional)

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

status ist running, während der Agent arbeitet, streaming, sobald Antworttext erzeugt wird, oder kurzzeitig ended, nachdem die Ausführung beendet ist. Die Antwort kann außerdem progress_events mit der jüngsten Aktivität enthalten, im selben Format wie stream_progress. Wenn status den Wert ended hat oder die Anfrage 404 not_found zurückgibt, rufen Sie die Nachrichten der Sitzung ab.

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 Ihr Konto 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 oder beim Aufruf von POST /invoke 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": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "thinking_variant": "claude-sonnet-5-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 model der Sitzung verwendet. Es wird beim Erstellen der Sitzung auf das Standardmodell des Agents gesetzt.

Modell aufrufen

POST /invoke

Sendet einen Prompt direkt an ein Modell, ohne Agent, Sitzung oder Tools. Antworten werden standardmäßig per SSE gestreamt; setzen Sie stream: false für JSON.

Anfragetext

Beispiel

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

Antwort 200 OK

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

Antworten mit Datenstromübertragung senden stream_started, dann stream_delta-Ereignisse, während das Modell Text erzeugt, und enden mit stream_ended, das usage enthält. Verketten Sie die chunk_content-Werte in der Reihenfolge von seq, um die per Datenstromübertragung übertragene Antwort zusammenzusetzen. Schlägt die Anfrage fehl, wird vor stream_ended ein stream_error gesendet. Ereignisse enthalten id statt session_id und run_id.

usage.cost ist null, wenn die Kosten nicht verfügbar sind. Schlägt eine Anfrage ohne Datenstromübertragung fehl, nachdem der Modellaufruf begonnen hat, enthält die Fehlerantwort die Felder id und usage auf oberster Ebene.

Anfragen mit Datenstromübertragung sind auf 120 Minuten begrenzt. Anfragen ohne Datenstromübertragung warten bis zu 30 Minuten auf das Ergebnis, statt 202 Accepted zurückzugeben, und geben einen Fehler zurück, wenn das Ergebnis bis dahin nicht vorliegt.

Fehler

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 offen, bis die Ausführung endet. Ausführungen sind auf 120 Minuten begrenzt. Nicht-streamende Nachrichtenanfragen warten bis zu 90 Sekunden und geben dann 202 Accepted zurück, während die Ausführung fortgesetzt wird. Für nicht-streamende POST /invoke-Anfragen siehe Modell aufrufen.

Verbindungs-Kopfzeilen

Nachrichten-Datenströme setzen 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. Datenströme von POST /invoke setzen kein X-Run-Id; verwenden Sie die id in stream_started.

Wiederverbindung und Wiederherstellung

SSE-Datenströme werden nicht erneut abgespielt. Wenn die Verbindung bei einer dauerhaften Anfrage 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 status: "ended" oder 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 Nachrichten auflisten 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.

Setzen Sie include_progress: false in einer Nachrichtenanfrage, 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":"my-support-agent"},"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 eine abgebrochene Ausführung:

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 Endbenutzer 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 noch überspringt oder 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 prüfen Sie die Ausführung mit Ausführungsstatus abrufen 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 Endbenutzer und Agent stummzuschalten, geben Sie mcp_server_id und mute an. mute akzeptiert eine Dauer wie 30m, 24h oder 7d oder 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 POST /messages-, POST /sessions/{session_id}/messages- und POST /invoke-Anfrage wird vor Beginn der Ausführung eine Guthabenreservierung von $0,50 auf Ihr Guthaben gelegt. Damit werden Mittel für die Anfrage reserviert. Eine Nachricht, die in eine aktive Ausführung eingereiht wird (202 Accepted mit status: "queued"), erzeugt keine zusätzliche Reservierung; die Nutzung der aktiven Ausführung wird gegen Ihr verbleibendes Guthaben geprüft.

Nach Abschluss der Anfrage wird die Reservierung auf die tatsächlichen Kosten abgerechnet und die Differenz freigegeben. Übersteigen die tatsächlichen Kosten die Reservierung, wird die Differenz ebenfalls berechnet, sodass Ihr Guthaben unter null fallen kann. Bei abgebrochenen und fehlgeschlagenen Anfragen wird nur die bereits entstandene Nutzung berechnet. Schlägt eine Anfrage fehl, bevor sie das Modell erreicht, wird die vollständige Reservierung freigegeben.

Aufgrund von Reservierungen kann Ihr verfügbares Guthaben während laufender Anfragen vorübergehend niedriger erscheinen. Sie benötigen mindestens $0,50 verfügbares Guthaben für eine POST /sessions/{session_id}/messages-Anfrage, eine flüchtige POST /messages-Anfrage oder eine POST /invoke-Anfrage. Eine dauerhafte POST /messages-Anfrage erstellt zusätzlich eine Sitzung und erfordert mindestens $0,51, um sowohl die Reservierung als auch die Gebühr für die Sitzungserstellung abzudecken.

Ratenbegrenzungen

Jedes Entwicklerkonto unterliegt drei Dimensionen der Ratenbegrenzung:

Eine Ausführung belegt ihren Slot für gleichzeitige Anfragen, bis sie endet, auch nach einer 202 Accepted-Antwort oder einer Client-Trennung. Eine POST /invoke-Anfrage belegt ihren Slot, bis sie abgeschlossen ist, auch nach einer Client-Trennung.

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.

Ein separates Limit pro IP-Adresse von 1.200 Anfragen pro 60 Sekunden gilt zusätzlich für alle Anfragen und gibt denselben Fehler 429 rate_limit_exceeded zurück.

Antwort-Kopfzeilen

Authentifizierte API-Antworten enthalten Ratenbegrenzungs-Kopfzeilen:

Wenn das Tageslimit überschritten wird, beschreiben X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset stattdessen das tägliche Zeitfenster.

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

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

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 lang oder Accept-Language 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 enthalten ein usage-Objekt auf oberster Ebene; cost ist null, wenn die Kosten nicht verfügbar sind.

Diese Fehler können bei jedem Endpunkt auftreten:

Endpunktspezifische Fehler sind direkt bei den jeweiligen Endpunkten dokumentiert.

Ausführungsfehler nach dem Start

Ausführungsfehler treten auf, nachdem eine Nachrichtenanfrage angenommen 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

„Sitzungen auflisten“ und „Nachrichten auflisten“ verwenden eine cursorbasierte Paginierung:

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

Übergeben Sie next_cursor URL-kodiert als Abfrageparameter cursor, um die nächste Seite abzurufen. Wenn has_more den Wert false hat, gibt es keine weiteren Ergebnisse. Ein limit außerhalb von 1-100 oder ein ungültiger Cursor gibt 400 bad_request zurück.

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]