Wave Developer API

Wave Developer APIは、自分の録音データにアクセスできるREST APIだ。https://api.wave.co/v1に対して、Wave内で作成したトークンを使ってリクエストを送れば、セッション一覧の取得、要約や文字起こしの閲覧、意味検索、音声のダウンロード、タイトルやアクションアイテムの更新ができるほか、録音の処理が完了した瞬間に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 — タイトル、長さ、Markdown形式の要約、メモ、タグ、お気に入り。電話の場合は発着信の方向と番号も含む。
• 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 — 一度に最大50セッションを、要約と文字起こし付きで取得。過去データをまとめて取り込むのに最適。
• GET /v1/folders、GET /v1/sessions/stats — フォルダ一覧、種類・プラットフォーム別の集計。

データの書き込み

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

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

レート制限

トークンごとに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からのプッシュ通知を受け取れる。Webhooks（Webhook）セクションで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がこれをラップしてくれる。

よくある質問