Jenova エージェント API リファレンス

ベース URL: https://api.jenova.ai/v1

Authentication: Authorization ヘッダー内のBearer token

目次

• 概要
• クイックスタート
• 基本概念
• 認証
• APIエンドポイント
  • メッセージ API
  • セッション API
  • 操作
  • クレジット
  • エージェント API
  • モデル
  • ドキュメント
• ストリーミング (SSE)
• MCPサーバー連携
• 請求
• レート制限
• エラー処理
• ページネーション
• ローカライゼーション
• プライバシーとデータ
• サポート

概要

数分で、製品やワークフローの中でカスタムエージェントを実行できます。どんなタスク向けにもエージェントをセットアップし、モデルとツールを自由に選べば、エージェントハーネス、データベース、スケールは Jenova が処理します。

フルエージェントスタック:

• マネージドエージェントハーネス: 呼び出しは 1 回、戻ってくるのは完成した成果物。エージェントが調査、推論、ツール呼び出しを行い、ファイルまで仕上げます。指示したとおりに。
• 無限のコンテキストとメモリ: RAG 駆動のコンテキスト管理と独自のセッション状態追跡により、会話の中では無限のメモリが実現します。
• ツールと MCP のライブラリ: 検索、画像生成、メールなど、30 以上のツールと MCP サーバーのライブラリに接続できるほか、独自の MCP サーバーを組み込むことも可能です。
• どのモデルへもシームレスに切り替え: OpenAI、Anthropic、Google、xAI、主要なオープンソースプロバイダーのモデルをデプロイし、パラメータ 1 つでモデル間を切り替えられます。
• マネージドナレッジと RAG: チャンキング、インデックス作成、格納、検索まで、エンドツーエンドの RAG パイプラインを Jenova が処理します。
• 大規模運用で実証済み: 本番環境で数百の稼働エージェントを支える、鍛え抜かれたインフラにデプロイ。クラスタのプロビジョニング、スケーリング、保守は一切不要です。

クイックスタート

1. APIキーの取得

www.jenova.ai/platform の開発者ダッシュボードからAPIキーを生成します。キーは jnv_sk_* の形式で、Bearer tokenとして渡されます。

2. エージェントの選択または作成

プラットフォーム上のビルド済みエージェントを選択するか、指示、モデル設定、ナレッジベースファイル、ツール、MCPサーバーを備えたカスタムエージェントをダッシュボードで作成します。

3. 最初のメッセージの送信

セッションを作成し、1回の呼び出しでメッセージを送信します。

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

レスポンスは 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"}}

後続のリクエストのために、stream_started から session_id を取得しておいてください。同期的なJSONレスポンスについては、メッセージの送信を参照してください。

基本概念

エージェント

APIを通じて開発者がやり取りするAIエージェントです。各エージェントには一意のslug（例：my-support-agent）があり、API呼び出しの agent の値として使用します。

• ビルド済み: プラットフォーム上の既存のエージェントから選択します。
• カスタム: ダッシュボードで、指示、モデル、ナレッジベース、ツール、MCPサーバーを指定して独自に設定します。

セッション

エンドユーザーとエージェントの間の、独立した会話スレッドです。

• 識別子: プレフィックス付きID（例：ses_abc123）。
• 範囲: 同一のエージェントおよびエンドユーザーに対して複数のセッションが存在でき、それぞれが独立した会話状態を持ちます。
• ライフサイクル: セッションはAPI経由で削除されるまで無期限に保持されます。セッションを必要としない単発タスクの場合は、ephemeral: true を指定して POST /messages を使用してください。
• プラットフォームの分離: APIのセッションは、Jenovaウェブアプリ内の会話とは分離されています。エンドユーザー、セッション履歴、および請求は、APIとウェブアプリの間で独立しています。

メッセージ

セッションの会話履歴内の1件のエントリであり、メッセージ APIエンドポイントから返されます。各メッセージには、type（user または agent）と name を含む構造化された from オブジェクトに加え、メッセージの type が含まれます。

• external - チャットコンテンツとして表示されることを意図した会話メッセージです。
• internal - 実行中のツール呼び出しや検索など、エージェントの作業ステップを表す任意のメッセージです。

実行

メッセージを送信した際に作成される、単一のエージェント実行です。実行には run_id があり、アクティブな間はイベントをストリーミングする場合があり、1件以上の完了済みメッセージを生成する場合があります。各セッションでは、一度にアクティブな実行を1つのみ持つことができます。

エンドユーザー

user フィールドは、セッションを開発者のアプリケーション内のエンドユーザーに紐付けます。開発者の内部ユーザーIDやUUIDなど、安定した不透明なIDを使用してください。アプリケーションで必要としない限り、メールアドレスなどの個人情報の使用は避けてください。同じ user の値で作成されたセッションはグループ化され、ユーザー単位でのセッション一覧取得が可能になります。

user を省略すると、そのセッションは開発者のアカウントに紐付けられ、後からエンドユーザー単位での絞り込みができなくなります。本番環境では user を必ず渡してください。

既存セッションへのリクエスト（パスに {session_id} を含むすべてのエンドポイント）では、user は任意の所有権チェックとして機能します。指定する場合は、そのセッションの作成時に使用された user の値と一致している必要があります。一致しない場合、APIは 404 session_not_owned を返します。GET および DELETE リクエストではクエリパラメータとして、POST および PATCH リクエストではJSONボディ内で送信してください。POST または PATCH で user をクエリパラメータとして指定すると、400 bad_request が返されます。

認証

すべてのリクエストは、Authorization ヘッダーに Bearer token を付与して認証してください。

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

APIキーは開発者ダッシュボードから生成されます。

User-Agent は任意です。SDKが診断のために設定する場合がありますが、APIとしては必須ではありません。

キー形式: キーは接頭辞 jnv_sk_ で始まり、続いてbase62エンコードされたランダムな文字列が付きます。

制限: 各開発者アカウントは、最大10個のアクティブなAPIキーを持つことができます。

APIエンドポイント

メッセージ API

メッセージの送信は主要なAPIパスです。最初のメッセージには POST /messages を使用してください。これにより1回のリクエストでセッションが作成され、実行が開始されます。取得済みの session_id を継続する場合は POST /sessions/{session_id}/messages を使用してください。

メッセージの送信

POST /messages

永続的なセッションを作成し、最初のメッセージを1つのリクエストで送信します。セッションIDを返さず、継続もできないストリーミングの単発リクエストにする場合は、ephemeral: true を設定してください。そのデータはリクエスト完了後まもなく削除されます。

リクエストボディ

例 - ストリーミング（デフォルト）

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

レスポンスはSSEストリームです（イベント形式についてはストリーミング (SSE)を参照してください）。永続的なリクエストには新しい session_id が含まれますが、ephemeral: true のリクエストでは session_id が省略され、ストリーミングを使用する必要があります。

例 - JSON（非ストリーミング）

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

レスポンス

ストリーミングレスポンスは、ストリーミング (SSE)で説明されているSSEイベントを送出します。非ストリーミングレスポンスは、セッションの継続で示されているように、リクエストに対する stop_reason と usage を含むメッセージオブジェクトを返します。stop_reason は end_run で、エージェントがメッセージを生成した後に実行がキャンセルされた場合は user_cancelled です。

エージェントがメッセージを生成する前に実行がキャンセルされた場合、APIは status: "cancelled"、session_id、run_id、stop_reason: "user_cancelled"、usage を含む 200 OK を返します。

非ストリーミングの実行が90秒経過してもまだ処理中の場合、APIは 202 Accepted を返し、status: "processing"、session_id、run_id、および人間が読める形式の message を含みます。実行はレスポンス後またはクライアント切断後も継続されます。セッションのメッセージを確認するか、長時間のワークフローにはストリーミングを使用してください。

エラー

セッションの継続

POST /sessions/{session_id}/messages

既存の永続セッションにメッセージを送信し、エージェントのレスポンスを受け取ります。レスポンスはデフォルトでSSE経由でストリーミングされます。JSONで受け取るにはstream: falseを設定してください。

リクエストボディ

例 - ストリーミング（デフォルト）

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

例 - JSON（非ストリーミング）

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

レスポンス 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"
  }
}

セッションに既にアクティブな実行またはキュー待ちのメッセージがある場合、APIはstatus: "queued"、session_id、run_id、message_idを含むJSONの202 Acceptedを返します。ユーザーメッセージはアクティブな実行によって処理されます。additional_context を含むリクエストの場合は、代わりに 409 busy を返します。

非ストリーミングレスポンスは、エージェントがメッセージを生成する前に実行がキャンセルされた場合の status: "cancelled" レスポンスを含め、メッセージの送信と同じルールに従います。

エラー

冪等性

POST /messages、POST /sessions/{session_id}/messages、POST /invoke は、任意の Idempotency-Key ヘッダー（最大255文字）を受け付けます。論理的なユーザー送信ごとに一意のキーを使用することで、ネットワークのリトライや二重送信によって重複した実行が作成されることを防げます。キーは24時間保持されます。

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

非ストリーミング: リトライすると、保存済みのレスポンスが Idempotent-Replayed: true ヘッダー付きで返されます。これには、リクエストの処理開始後に返されたエラーも含まれます。保存済みの 202 Accepted レスポンスは変更されずにそのまま返されるため、結果を確認するには 実行ステータスの取得 または メッセージ一覧の取得 を使用してください。検証エラーやクレジット不足エラーなど、処理開始前に拒否されたリクエストは保存されないため、リトライすると改めて評価されます。

ストリーミング: ストリームは再生されません。POST /messages および POST /sessions/{session_id}/messages では、実行中または完了後にリトライすると、元の run_id、および永続的なリクエストの場合は session_id を含む冪等性エラーが返されます。永続的なリクエストの場合、実行中の実行を確認するには 実行ステータスの取得 を使用し、永続化された結果を取得するには メッセージ一覧の取得 を使用してください。ストリーミングの POST /invoke の結果は、ストリームが閉じた後は取得できません。 POST /invoke のリトライでは、run_id と session_id の代わりに元の id が返されます。

完了済みストリーミングのリトライ例:

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

冪等性エラー

メッセージ一覧の取得

GET /sessions/{session_id}/messages

セッションのメッセージのページネーション付き一覧を返します。デフォルトでは external の会話メッセージのみが返されます。最初のページには最新のメッセージが含まれます。各ページ内では、メッセージは時系列順（古いものから新しいものへ）で並びます。sequence はセッション内でのメッセージの並び順を示す番号です。

クエリパラメータ

例

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

レスポンス 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
}

メッセージオブジェクト

ファイルオブジェクト

エラー

メッセージの取得

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

IDを指定して、単一のメッセージを取得します。

クエリパラメータ

レスポンス 200 OK

一覧レスポンスと同じ構造の、単一のメッセージオブジェクトを返します。

エラー

ファイル添付

公開アクセス可能なHTTPS URLを file_urls フィールドに指定します。

サポートされる形式

• 画像: JPG、JPEG、PNG、WebP
• 文書: PDF、DOCX、XLSX、PPTX、TXT、CSV、RTF、MD、HTML、XML、JSON、LOG
• コード: JS、TS、TSX、JSX、PY、Java、Go、C、CPP、H、HPP、CS、RB、PHP、RS、Swift、KT、Scala、SQL、CSS、YAML、YML

ファイルURLは、リクエストの受け付け時ではなく、実行中にエージェントが読み込む時点で取得されます。取得できないURLや20 MBを超えるファイルは読み込まれませんが、リクエスト自体は拒否されません。

メッセージを一覧取得する際、添付されたファイルはメッセージの files 配列に表示されます。

追加コンテキスト

エンドユーザーのアカウント情報など、1件のメッセージに限った名前付きコンテキストを additional_context で渡します。メッセージ履歴には保存されません。

customer_profile や order_details のような説明的な名前を使用してください。

name または content が欠落しているか文字列でない項目は 400 invalid_payload を返します。その他の無効な項目は 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."
      }
    ]
  }'

セッション API

セッションは、エンドユーザーとエージェントの間で持続する会話です。ほとんどの統合では、POST /messages によって暗黙的にセッションを作成できます。

セッションの作成

POST /sessions

特定のエージェントに紐づく空の永続セッションを作成します。最初のメッセージより前にセッションIDが必要な場合に使用します。それ以外の場合は POST /messages の利用を推奨します。

注記: ephemeral は POST /sessions では受け付けられません。単発のリクエストには、POST /messages を ephemeral: true とともに使用してください。

リクエストボディ

例

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

レスポンス 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"
}

セッションオブジェクト

エラー

セッション一覧の取得

GET /sessions

開発者のセッションのページネーションされた一覧を、最終更新日時の新しい順に返します。

クエリパラメータ

例

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

レスポンス 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
}

エラー

セッションの取得

GET /sessions/{session_id}

IDを指定して単一のセッションを取得します。

クエリパラメータ

レスポンス 200 OK

セッションオブジェクトを返します。

エラー

セッションの名前変更

PATCH /sessions/{session_id}

セッションの表示名を更新します。

リクエストボディ

レスポンス 200 OK

更新されたセッションオブジェクトを返します。

エラー

セッションの削除

DELETE /sessions/{session_id}

セッションとそのすべてのメッセージを永久に削除します。セッションにアクティブな実行があってはいけません。

レスポンス 204 No Content

エラー

操作

これらのエンドポイントは、永続的なセッションに対する復旧および編集用のコントロールです。ほとんどの統合ではアクティブな実行のキャンセルのみで十分ですが、意図的にセッション状態を変更または復旧したい場合には、他の操作を使用してください。すべての操作は、エンドユーザー で説明されている任意の所有権ガード user をサポートします。

アクティブな実行のキャンセル

POST /sessions/{session_id}/cancel

アクティブなエージェント実行をキャンセルします。キャンセル前に完了済みだったメッセージは削除されません。

リクエストボディ

レスポンス 204 No Content

エラー

アクティブな実行のアンドゥ

POST /sessions/{session_id}/undo

アクティブな実行をキャンセルし、停止を待ってから、その実行によって既に追加されたメッセージを削除します。アンドゥが発行された後は、追加の出力は保存されません。

リクエストボディ

レスポンス 200 OK

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

いずれのメッセージも完了する前に実行がキャンセルされた場合、deleted は空の配列になります。

エラー

直近のメッセージの削除

POST /sessions/{session_id}/messages/delete

アイドル状態のセッションから、internal メッセージを含む直近の count 件のメッセージを削除します。これらを確認するには、メッセージ一覧の取得 で include=all を使用してください。セッションはアクティブな実行を持っていない必要があります。

リクエストボディ

レスポンス 200 OK

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

エラー

セッションのフォーク

POST /sessions/{session_id}/fork

元のセッションを指定したメッセージまでコピーして、新しいセッションを作成します。元のセッションはアクティブな実行を持っていない必要があります。

リクエストボディ（任意）

レスポンス 201 Created

セッション作成時と同じ構造の、新しく作成されたセッションオブジェクトを返します。

エラー

実行ステータスの取得

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

アクティブな実行の現在の状態を返します。SSE接続が切断された場合や、run_id を返す冪等性レスポンスを受け取った場合に使用します。実行が完了した後は、GET /sessions/{session_id}/messages で結果を取得してください。

レスポンス 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、レスポンスのテキストが生成され始めると streaming、実行の終了直後の短い間は ended になります。レスポンスには、stream_progress と同じ形式で直近のアクティビティを示す progress_events が含まれる場合もあります。status が ended の場合、またはリクエストが 404 not_found を返した場合は、セッションのメッセージを取得してください。

エラー

クレジット

残高の取得

GET /credits/balance

開発者の現在のクレジット残高を返します。

レスポンス 200 OK

{
  "balance": "123.45"
}

エージェント API

ダッシュボードでカスタムエージェントを作成・編集できます。APIによるエージェントの作成・編集のサポートは近日公開予定です。

スケジュール実行/バックグラウンドワークフローは、現時点ではAPI経由でサポートされていません。サポートは近日公開予定です。

エージェント一覧の取得

GET /agents

開発者のアカウントで利用可能なエージェントを返します。セッションの作成やメッセージの送信時には agent の値を使用してください。

レスポンス 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"
    }
  ]
}

モデル

モデル一覧の取得

GET /models

メッセージ送信時または POST /invoke の呼び出し時に model フィールドで使用できるすべてのモデルを返します。

レスポンス 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"
    }
  ]
}

thinking_variant を持つモデルは、拡張推論に対応しています。これを有効にするには、model フィールドにバリアントIDを直接指定してください。

メッセージ送信時に model を指定しない場合、セッションの model が使用されます。この値はセッション作成時にエージェントのデフォルトモデルに設定されます。

モデルの呼び出し

POST /invoke

エージェント、セッション、ツールを使わずに、プロンプトをモデルへ直接送信します。レスポンスはデフォルトでSSE経由でストリーミングされます。JSONで受け取るにはstream: falseを設定してください。

リクエストボディ

例

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

レスポンス 200 OK

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

ストリーミングレスポンスは、stream_started を送信し、モデルがテキストを生成する間 stream_delta イベントを送信した後、usage を含む stream_ended で終了します。ストリーミングされた応答を構築するには、chunk_contentの値をseqの順序で連結してください。リクエストが失敗した場合は、stream_ended の前に stream_error が送信されます。イベントには session_id と run_id の代わりに id が含まれます。

コストが取得できない場合、usage.cost は null になります。モデル呼び出しの開始後に非ストリーミングリクエストが失敗した場合、エラーレスポンスには、トップレベルの id フィールドと usage フィールドが含まれます。

ストリーミングのリクエストの上限は120分です。非ストリーミングのリクエストは 202 Accepted を返さずに結果を最大30分間待機し、それまでに結果が得られない場合はエラーを返します。

エラー

ドキュメント

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

このリファレンスをMarkdown形式で返します。言語を選択するには lang を使用してください。

ストリーミング (SSE)

stream が省略されている、または true（デフォルト）の場合、メッセージのレスポンスはServer-Sent Eventsとして配信されます。取得や表示の準備が整ったメッセージを識別するには、message_completed イベントを使用してください。

タイムアウト: SSE接続は実行が終了するまで開いたままになります。実行時間の上限は120分です。非ストリーミングのメッセージリクエストは最大90秒間待機し、その後は実行が継続中であっても 202 Accepted を返します。非ストリーミングの POST /invoke については、モデルの呼び出しを参照してください。

接続ヘッダー

メッセージストリームでは、以下のヘッダーが設定されます。

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

X-Run-Id は最初のSSEイベントより前から利用可能です。POST /invoke のストリームでは X-Run-Id は設定されないため、stream_started の id を使用してください。

再接続とリカバリ

SSEストリームは再生（リプレイ）されません。永続的なリクエストで接続が切断された場合は、取得済みの session_id と run_id を使用して状態を復元してください。

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

実行がまだアクティブな場合、現在のステータス、部分的なテキスト、直近の進行状況が返されます。status: "ended" または 404 not_found が返された場合、その実行はもはやアクティブではないため、セッションのメッセージを取得して完了済みの出力を突き合わせてください。

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

フレーム形式

各SSEフレームは、次の標準形式に従います。

event: <event_type>
data: <json_payload>

2つの改行で各フレームが終端します。

イベントタイプ

ストリームには、ライフサイクル、テキスト差分、思考、進行状況、警告、メッセージ完了、MCP接続、エラー、最終、ping の各イベントが含まれます。一部のイベントタイプは、関連する場合にのみ送信されます。

エフェメラルリクエスト(ephemeral: true)の場合、すべてのSSEイベントでsession_idが省略されます。その1つのストリーム内でイベントを関連付けるには、run_idのみを使用してください。

永続的リクエストの最終的な整合性確認については、stream_endedを待ってから、メッセージ一覧の取得を呼び出してください。

実行スコープのイベントに共通するフィールド:

stream_started

実行が開始されたときに一度送信されます。

stream_delta

エージェントが表示用の応答テキストを生成する間、繰り返し送信されます。ストリーミングされた応答を構築するには、chunk_contentの値をseqの順序で連結してください。

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

stream_thinking

エージェントが思考出力を発する間、繰り返し送信されます。これは、独立した思考インジケーターやトレース表示に使用してください。最終的な応答テキストに連結しないでください。

stream_progress

ドキュメントの読み取り、Web検索、ユーザーアクション待ちなど、生成中にユーザーに表示するアクティビティを報告します。これらのイベントは一時的なUI表示を目的としています。不明なフィールドは無視してください。正式なメッセージ履歴には完了済みメッセージを使用してください。

メッセージリクエストでinclude_progress: falseを設定すると、stream_progressのみを省略できます。ライフサイクルイベント、ping、message_completed、エラー、終端イベントは、関連する場合には引き続き送信されます。

一部の進行状況イベントには、任意の表示用ヒントとしてurl、file_name、server_nameが含まれる場合があります。

message_completed

メッセージが完了し、取得または表示できる状態になるたびに送信されます。

これは境界マーカーであり、完全なメッセージオブジェクトではありません。内容やメタデータが必要な場合は、メッセージを取得してください。

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

エージェントが続行する前に、エンドユーザーが1つ以上のMCPサーバーへ接続または認可する必要がある場合に送信されます。このイベントはストリーミングモードでのみ利用できます。

mcp_connection_resolved

MCP接続ユーザーアクションが解決された、または期限切れになった場合に送信されます。

共通の実行スコープフィールド以外の追加フィールドはありません。

warning

実行中の致命的でない警告に対して送信されます。

stream_error

実行が失敗したときに送信されます。続いて、success: falseおよびstop_reason: "error"を伴う最終的なstream_endedイベントが送信される場合があります。

stream_ended

実行が終了すると1回だけ送信されます。これはストリームの最後のイベントです。

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

キャンセルされた実行の例:

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

ping

プロキシ/CDNのタイムアウトを防ぐため、15秒ごとに送信されるキープアライブフレームです。クライアント側では無視してください。

MCPサーバー連携

Model Context Protocol (MCP) を介して、開発者のエージェントを外部ツールに接続できます。

• Jenova管理のMCPサーバー: 検索、コンテンツ取得、ドキュメント生成などの組み込み機能を提供する、Jenovaがホストするサーバー
• リモートMCPサーバー: 開発者のエージェント用に設定された、その他のリモートMCPサーバー

MCPサーバーは、エージェントの作成または編集時にダッシュボードで設定する必要があります。独自のMCPサーバーを使用するには、カスタムエージェントに追加した上で、そのエージェントをAPI経由で呼び出してください。APIはエージェントの設定で有効化されたツールを実行するため、APIリクエスト側で追加の設定は不要です。

エージェントがレスポンス生成中にMCPツールを使用する場合、進捗イベントが発生に応じてストリームに送信されます。

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

実行中にエンドユーザーがMCPサーバーへ接続または認可する必要がある場合、ストリーミングレスポンスに mcp_connection および mcp_connection_resolved イベントが含まれることがあります。接続対象サーバーの一覧をエンドユーザーに提示し、auth_url が存在する場合はそれを開いてください。エンドユーザーがサーバーに接続または認可している間は、SSEストリームを開いたままにしてください。

認可が完了すると、Jenovaはtokenを保存し、認可ウィンドウには完了ページが表示され、同じ実行が自動的に継続します。エンドユーザーがメッセージを再送信する必要はありません。

エンドユーザーが user_action_deadline_unix までに接続、認可、またはスキップかミュートを行わなかった場合、実行は stop_reason: "user_action_timeout" で終了します。また、POST /sessions/{session_id}/cancel を使ってアクティブな実行をキャンセルすることもできます。

auth_url はクライアント側で保存してください。認可中にクライアントが切断された場合でも、このURLは user_action_deadline_unix まで有効です。永続リクエストでは、実行ステータスの取得 で実行を確認するか、実行終了後にメッセージを取得してください。

非ストリーミングリクエスト（stream: false）はMCP接続ユーザーアクションをサポートしません。この操作が必要になる可能性のあるエージェントにはストリーミングを使用してください。

MCP接続をスキップ

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

保留中のMCP接続ユーザーアクションを破棄し、その接続なしで実行を続行できるようにします。

同じエンドユーザーとエージェントの組み合わせに対する特定サーバーの今後の接続プロンプトをミュートするには、mcp_server_id と mute を含めてください。mute には 30m、24h、7d などの期間、または forever を指定できます。

リクエストボディ

レスポンス 204 No Content

ストリームは mcp_connection_resolved を発行し、その後、実行は同じ run_id のまま継続します。

エラー

請求

すべてのコストは、開発者のクレジット残高から差し引かれます。使用量の確認とクレジットのチャージは www.jenova.ai/platform で行えます。

料金

メッセージのコストは、以下の要素に依存します。

• モデル - モデルごとにトークン単価が異なります
• コンテキストの長さ - セッションが長くなるほど、1リクエストあたりの入力トークン消費量が増加します
• ワークフローの複雑さ - ワークフローが長くなったり、ツールの使用(Web検索、ファイル生成、文書解析)が増えると、トークンの総消費量が増加します

実際のコストは、ストリーミングリクエストでは stream_ended.usage.cost、非ストリーミングのJSONリクエストでは usage.cost として返されます。

クレジットホールド

POST /messages、POST /sessions/{session_id}/messages、POST /invoke の各リクエストごとに、実行開始前に開発者のクレジット残高に対して**$0.50のホールド**が設定されます。これはリクエストのための資金を確保するものです。アクティブな実行のキューに入れられたメッセージ（status: "queued" を含む 202 Accepted）では、追加のホールドは発生しません。アクティブな実行の使用量は、開発者の残りの残高と照合されます。

リクエストが完了すると、ホールドは実際のコストで確定され、差額は解放されます。実際のコストがホールドを上回った場合は差額も課金されるため、残高がマイナスになることがあります。キャンセルまたは失敗したリクエストに対しては、すでに発生した使用量分のみが課金されます。リクエストがモデルに到達する前に失敗した場合、ホールドは全額解放されます。

ホールドがあるため、リクエストの処理中は、利用可能な残高が一時的に低く表示される場合があります。POST /sessions/{session_id}/messages、一時的な POST /messages、または POST /invoke リクエストには、少なくとも**$0.50の利用可能な残高が必要です。持続的な POST /messages リクエストはセッションも作成するため、ホールドとセッション作成料をカバーするために少なくとも$0.51**が必要です。

レート制限

すべての開発者アカウントには、次の3つのレート制限の次元が適用されます。

実行は、202 Accepted レスポンスの後やクライアント切断後も、終了するまで同時実行スロットを保持します。POST /invoke リクエストは、クライアント切断後も、完了するまでスロットを保持します。

GET および HEAD リクエストは同時実行スロットを消費しません。cancel、undo、mcp/connection/skip も同時実行スロットを消費しないため、すべてのスロットが使用中でもこれらの操作は利用できます。これらのリクエストは引き続き RPM と RPD にカウントされます。

これとは別に、60秒あたり1,200リクエストのIPごとの制限もすべてのリクエストに適用され、超過すると同じ 429 rate_limit_exceeded エラーが返されます。

レスポンスヘッダー

認証済みのAPIレスポンスには、レート制限に関するヘッダーが含まれます。

1日の上限を超えた場合、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset は代わりに1日単位のウィンドウを示します。

制限を超えると、APIは429 Too Many Requestsを返します。

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

エラー処理

即時に返されるHTTPエラーと非ストリーミングの実行エラーは、一貫したエンベロープ形式に従います。

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

エラーメッセージはlangまたはAccept-Languageに基づいてローカライズされます（ローカライゼーションを参照してください）。

ストリーミングの実行エラーはstream_errorイベントとして配信されます。失敗した実行では、success: falseかつstop_reasonが設定された最終的なstream_endedイベントが送信される場合もあります。非ストリーミングの実行エラーにはトップレベルのusageオブジェクトが含まれ、コストが取得できない場合、costはnullになります。

以下のエラーはすべてのエンドポイントで発生する可能性があります。

エンドポイント固有のエラーについては、各エンドポイントの説明内にドキュメント化されています。

開始後の実行エラー

実行エラーは、メッセージリクエストが受け付けられた後に発生することがあります。ストリーミングモードでは、これらはstream_errorイベントとして表示され、その後にsuccess: falseを伴うstream_endedが続く場合があります。非ストリーミングモードでは、以下のHTTPステータスを伴うJSONエラーレスポンスとして返されます。

ページネーション

セッション一覧の取得とメッセージ一覧の取得はカーソルベースのページネーションを使用します。

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

次のページを取得するには、next_cursorの値をURLエンコードしてcursorクエリパラメータとして渡してください。has_moreがfalseの場合、それ以上の結果はありません。1〜100の範囲外のlimitまたは無効なカーソルを指定すると、400 bad_requestが返されます。

ローカライゼーション

すべてのエンドポイントは、エラーメッセージやローカライズされたコンテンツの言語を制御するための任意のlangクエリパラメータを受け付けます。

任意のリクエストURLに?lang=xxを追加できます。

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

対応言語: en、zh、ja、ko、es、fr、de、it、pt、ru、id、th、vi

プライバシーとデータ

Jenovaは、Jenovaのモデルの学習にAPIのプロンプト、出力、会話履歴、アップロードされたファイル、エージェントの指示、またはナレッジベースを使用することはありません。

サードパーティのモデルプロバイダーについては、Jenovaは、顧客のコンテンツがプロバイダーのモデルの学習に使用されないようにするための商用APIチャネル、アカウント設定、契約上の取り決め、またはオプトアウトを利用しています。

Jenovaは、米国のインフラストラクチャを使用してAPIデータを保存・処理します。サードパーティのプロバイダーは、プライバシーポリシーおよび利用規約に記載されているとおり、他の法域でデータを処理する場合があります。

詳細については、利用規約、プライバシーポリシー、使用ポリシーを参照してください。

サポート

• ダッシュボード: www.jenova.ai/platform
• メール: [email protected]