Wave デベロッパー API

Wave デベロッパー API は、自分のレコーディングを操作するための REST API だ。自分で作成したトークンを使って https://api.wave.co/v1 にアクセスすれば、セッション一覧の取得、要約や文字起こしの読み取り、意味による検索、音声のダウンロード、タイトルやアクションアイテムの更新ができるし、レコーディングの処理が終わった瞬間に Webhook でプッシュ通知を受け取ることもできる。

すべての Wave プランで無料で使え、アクセスできるのは常に自分自身のアカウントだけだ。

トークンを作成する

すべてのリクエストで、これをベアラートークンとして送信する：

curl -H "Authorization: Bearer wave_api_xxx..." \
  https://api.wave.co/v1/sessions

トークン一覧には、各トークンの名前、wave_api_ プレフィックス、作成日時、最終使用日時が表示される。ゴミ箱アイコンから Revoke Token（「トークンを無効化」）を開ける — 無効化は即座に反映され、そのトークンを使っている処理はすべて 401 を受け取るようになる。

権限

権限はトークンごとに設定する。必要最小限の権限だけを付与しよう。

対応する権限がないままエンドポイントを呼び出すと、不足している権限を示す 403 が返る。

データを読み取る

• GET /v1/sessions — 新しい順、カーソルによるページネーション、type・since・folder・tag で絞り込み可能。処理が完了したセッションのみが返る。
• GET /v1/sessions/:id — タイトル、長さ、マークダウン形式の要約、メモ、タグ、お気に入り。電話の場合は発着信の方向と電話番号も含まれる。
• GET /v1/sessions/:id/transcript — 文字起こし全文の文字列と、タイムスタンプ・話者ラベル付きのセグメント。
• GET /v1/sessions/:id/action-items — 構造化されたアクションアイテムとバージョン番号。
• GET /v1/sessions/:id/media — 音声・動画の署名付き URL（有効期限は1時間）。
• POST /v1/sessions/search — セマンティック検索、最大50件、タグによる絞り込みも可能。
• POST /v1/sessions/bulk — 1回の呼び出しで最大50セッション、要約と文字起こし付き。過去分をまとめて取り込むのに最適。
• GET /v1/folders、GET /v1/sessions/stats — フォルダ一覧、種類・プラットフォーム別の合計。

データを書き込む

PATCH /v1/sessions/:id で、タイトル、メモ、タグ、お気に入り、アクションアイテムを設定できる。アクションアイテムについては、まず読み取ってから取得したバージョンを渡し返すこと — そうすれば、Wave アプリ側での同時編集は上書きされずに拒否される。POST /v1/folders とフォルダメンバーシップ関連のエンドポイントでセッションを整理できる。フォルダは排他的ではないので、1つのセッションが複数のフォルダに属することもできる。

DELETE /v1/sessions/:id は完全な削除であり、アプリ内での削除とは異なる。復元はできないものと考えてほしい。

共有

トークンは本人として振る舞うため、上記の権限があれば、他の Wave ユーザーがあなたと共有したセッションも読み取れる。GET /v1/shared-sessions で一覧を取得でき、GET /v1/shared-sessions/{owner_id}/{id} とその /transcript、/action-items、/media で個別に読み取れる。GET /v1/sessions に include=shared を付けると、自分のセッション一覧に共有セッションも混在させられる。この場合、各行には access（owner または shared）が含まれ、共有された行には所有者の情報も付く。共有された行はフォルダやタグでの絞り込みができず、共有セッションは読み取り専用で、検索は自分のセッションのみが対象になる。

Share Sessions & Manage Access 権限があれば、トークンから自分のセッションを共有できる：/v1/sessions/{id}/sharing でアクセス権を持つ人を確認でき、その配下のルートで招待リンクの作成、メールでの招待（1回の呼び出しで最大10件のアドレス）、保留中の招待のキャンセル、特定の人の削除、リンクのリセットができる。全一覧と制限については、Claude、ChatGPT、API、CLI からのセッション共有を参照してほしい。

レート制限

トークンごとに1分あたり60リクエスト、1日あたり10,000リクエストまで許可される。レスポンスには X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が含まれ、429 には Retry-After が付いてくる — すぐに再試行せず、間隔を空けよう。

同じ検索クエリを1時間に10回を超えて繰り返した場合も 429 が返る。同一の検索は同一の結果を返すので、新着分を見つけるには Webhook か GET /v1/sessions?since= を使ってほしい。

Webhook

ポーリングの代わりに、Wave からあなたに POST してもらうこともできる。Webhooks セクションで Add Webhook（「Webhook を追加」）をクリックし、Endpoint URL（「エンドポイント URL」、HTTPS のみ、プライベートアドレスに解決される URL は拒否される）を入力し、イベントを選んで Create Webhook をクリックする。Signing Secret（「署名シークレット」）は一度だけ表示されるので、その時に保存しておこう。Webhook は最大5個まで設定できる。

現在登録できるイベントは3つ：Session Completed（処理が完了し要約が取得可能になった後に一度だけ発火する — ほとんどの連携が欲しいイベント）、Session Updated、Session Deleted。

各配信はあなたのシークレットで署名され、X-Wave-Webhook-Id、X-Wave-Webhook-Timestamp、X-Wave-Webhook-Signature の各ヘッダーとともに届く。ペイロードを信頼する前に署名を検証すること。署名対象となる正確な文字列はAPI リファレンスに記載されている。

エンドポイントが10回連続で失敗すると、Wave はそれを Auto-disabled（「自動無効化」）とマークして送信を停止する。エンドポイントを修正したら、Webhook の行にある再有効化ボタンを使おう。

サーバーがない場合はイベントフィードを使う

公開 URL をホストできない場合は、代わりにポーリングしよう。GET /v1/events は、Wave がトークンごとに管理しているカーソル以降のイベントを返し、処理し終えたら POST /v1/events/ack でカーソルを進めれば、スクリプトを再起動してもすべてを再生することはない。ページはデフォルトで50件、最大200件まで。このフィードには Webhook のサブスクリプションには含まれないアクションアイテムの変更も含まれる。Read Event Feed 権限が必要。

ポーリングループを自分で書きたくないなら、Wave CLI の wave events tail がこれをラップしてくれる。

FAQ