概要

Ephemeral API は、HTTPS 上の JSON です。実行、ワークフロー、ファイル、接続、モデルはエンジンが提供します。ホスト型サービスでは、組織、メンバー、キー、請求は、別の組織 API が提供します。

ベース URL

これらのページの例では、エンジンのベースを、/v1 を除いた $EPHEMERAL_URL と表記しています。

認証

エンジンへのすべてのリクエストに、組織の API キーを Bearer トークンとして付けて送信します。

curl $EPHEMERAL_URL/v1/me \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY"

ホスト型のキーは eak_、セルフホストのキーは eph_ で始まります。キーは 1 つの組織に属するため、エンジンに組織 ID を渡す必要はありません。キーがエンドポイントを呼び出せるかどうかは、ロールによって決まります。ロールとキーをご覧ください。組織 API は、管理操作での API キーを拒否し、代わりにログイン中のオーナーまたは管理者を必要とします。組織をご覧ください。

人の代わりに動作するアプリケーション (MCP クライアントなど) は、代わりに OAuth 2.1 でログインできます (ホスト型のみ)。PKCE 付きの認可コードフロー、動的クライアント登録、スコープ member と admin に対応しています。アクセストークン (eoa_…、有効期間 1 時間) は同じ Authorization: Bearer ヘッダーで送り、その人が選んだ組織で動作します。ディスカバリー: 認可サーバーメタデータと保護リソースメタデータ。詳しくは MCP を参照してください。

{
  "organization_id": "org_5e2b8c91d4a7f03e6b1c9d2a8f4e7b10",
  "role": "member",
  "mode": "hosted",
  "compute_micros_per_second": 200,
  "default_max_cost_micros": 500000
}

リクエスト

• JSON は Content-Type: application/json を付けて送信します。例外はファイルのアップロードで、multipart フォームデータを使います。
• 未知のフィールドは 400 で拒否されます。そのため、フィールド名を誤るとエラーが返ります。
• タイムスタンプは、UTC の RFC 3339 形式の文字列です。
• _micros で終わる金額のフィールドは、米ドルの 100 万分の 1 を単位とする整数です。_cents で終わるフィールドは、セント単位の整数です。

エラー

エラーは、HTTP ステータスと、error に読みやすいメッセージを含む JSON ボディで返されます。

{ "error": "timeout_seconds must be between 1 and 3600", "code": "invalid_request" }

レート制限

エンジンへのリクエストには 1 分あたりの上限があります。Bearer トークン付きのリクエストはその認証情報ごとに数えられ、上限は 1 分あたり 600 リクエストです。GET /v1/models のようにトークンのないリクエストはクライアントアドレスごとに数えられ、上限は 1 分あたり 120 リクエストです。ウィンドウの長さは 1 分で、毎分の始まりでリセットされます。

エラーを含むすべてのエンジンのレスポンスに、現在の残りが示されます。RateLimit-Policy と RateLimit は IETF の RateLimit ヘッダー草案に従います（q は上限、w は秒単位のウィンドウ、r は残りリクエスト数、t はウィンドウがリセットされるまでの秒数）。X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset は、多くのクライアントがすでに読み取る名前で同じ値を返します。

RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=598;t=41
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 41

上限を超えると、エンジンは通常の JSON エラー（コード rate_limited）とともに 429 を返し、待つべき秒数を Retry-After ヘッダーで示します。すぐに再試行せず、その時間だけ待ってください。GET /v1/runs/{id}/events で実行を追う場合は、イベントごとではなく接続ごとに 1 回数えられます。

冪等な実行の作成

ネットワーク障害が起きると、実行が作成されたかどうか分からなくなることがあります。POST /v1/runs に、200 文字までの Idempotency-Key ヘッダーを付けて送信してください。そのキーを持つ実行が組織内にすでに存在する場合、Ephemeral は新しい実行を作成せず、既存の実行をステータス 200 で返します。新しい実行が作成されたときは 202 が返ります。

ページネーション

GET /v1/runs は、limit (1 から 100) または cursor を指定するとページ分割されます。レスポンスは {"items": [...], "next_cursor": "..."} です。次のページを取得するには、next_cursor を cursor として渡します。next_cursor が空の場合は、最後のページです。カーソルは不透明な値で、同じ status フィルターでのみ有効です。limit も cursor も指定しない場合、レスポンスは、直近 100 件の実行を含む単純な配列です。

バージョンと非推奨

API のバージョンはパスに含まれます。ここにあるエンドポイントはすべて /v1 の下にあります。同じバージョンの中での変更は追加だけです。新しいエンドポイント、新しい任意のリクエスト項目、新しいレスポンス項目、新しいイベントの種類が加わることがあります。既存の項目の名前と意味は変わらないので、クライアントは知らない項目を無視してください。

既存のクライアントを壊す変更は、新しいパスの新しいバージョンとして公開します。以前のバージョンは、新しいバージョンの公開から少なくとも 6 か月は動き続けます。非推奨の期間中は、レスポンスに Deprecation ヘッダーと、停止日を示す Sunset ヘッダーが付き、組織のオーナーにはメールでお知らせします。

リファレンス

エンジン API は OpenAPI 3.1 の記述（https://app.ephemer.al/openapi.json）としても公開されており、各オペレーションに必要なキーのロールが含まれます。キーのロール member と admin は、保護リソースメタデータの scopes_supported に機械可読な形で記載されています。