LISTEN API

外部ツールからLISTENの配信準備や分析を自動化するためのREST APIです。新しい外部連携には、このドキュメントに記載したREST APIを使用してください。スマホアプリで使用している既存GraphQL APIは変更しません。

はじめに

ベースURLは https://listen.style/api/v1 です。認証の手順でAPIトークンを発行し、必要な権限だけを付与してください。

curl 'https://listen.style/api/v1/podcasts' \
  -H "Authorization: Bearer $LISTEN_API_TOKEN" \
  -H 'Accept: application/json'

GET /podcasts は所有権を確認済みの番組を返します。data 内に id・title、meta 内に has_more・next_cursor を含みます。first は1〜100件（既定50件）、続きは after=next_cursorの値 で取得します。URLの {podcast} には番組IDを指定します。

目的から探す

• ファイルアップロード：動画・画像を送信する。大容量の分割アップロードにも対応。
• ビデオストック：RSS公開前に動画を準備し、修正・取消・紐づけを自動化する。
• ビデオ利用枠：残り利用枠と番組ごとの内訳を確認する。
• Webhook：変換失敗・紐づけ・利用枠の残量を通知で受け取る。
• RSS再取得：外部RSSの更新をLISTENへ取り込むよう依頼する。
• 文字起こしのアップロード：SRT・VTTを取り込む。
• チャプターのアップロード：外部で作った目次をアップロードする。
• アクセス解析エクスポート：対象プランで詳細データをCSV取得する。

共通仕様

JSON APIの成功時は data を返します（アクセス解析はCSV）。入力と出力の項目・利用条件は各ページを参照してください。チャプターの startTime やWebhook通知本文など、既存形式を維持している項目もあります。JSONの日時はUTCのISO 8601形式です。予定日時を送る際はタイムゾーンのオフセットを明記してください。

401 は未認証、403 は権限不足、404 は対象なし、409 は状態の競合・処理中、422 は入力や処理条件の不備、429 は回数制限です。message と、存在する場合は errors を確認し、エラーメッセージの文言に依存しないでください。

API共通で利用者ごとに1分60リクエストの制限があり、機能別の制限も適用されます。429 では Retry-After の秒数が経過してから再試行してください。リトライは間隔を広げ、登録では client_key、修正では expected_revision を活用してください。

試験的なAPIのため、仕様・制限は変更される場合があります。このドキュメントの範囲を外部公開APIとして案内し、内部APIの仕様には依存しないでください。