5分で終わる最初の呼び出し

このページから離れずに、ゼロから API でライブセッションを作るところまで進みます。

始める前に

  • 有料プランのアカウント。API は FREE には含まれません（リファレンス全文は無料のまま読めます）。
  • ワークスペース内のプレゼンテーション。これから作るセッションは既存のプレゼンテーションを実行します。

  1. 認証情報を作成する

    ワークスペースで 組織 → API を開き、content:write スコープの認証情報を作成します。シークレットは一度しか表示されないので、必ず保存してください。

    API キーを取得

    認証情報はユーザーではなく組織に属します。管理者であれば誰でも失効させられ、利用はすべて監査ログに残ります。必要なスコープだけを要求してください。読み取りには results:read、作成と進行には content:write です。

  2. セッションを作成して開く

    X-API-Key ヘッダーにキーを入れて、既存のプレゼンテーションからセッションを作成し、それを開きます。

    curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/sessions \
  -H "X-API-Key: vz_live_…" \
  -d '{ "presentation_id": "prs_8f3k2" }'

curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/sessions/ses_71xw9/open \
  -H "X-API-Key: vz_live_…"

    セッションは DRAFT の状態で作られ、開いた時点で参加コードが発行されてルームが使えるようになります。レスポンスの X-RateLimit-* ヘッダーにもご注目ください。すべての応答に含まれ、60秒のウィンドウ内であと何回呼び出せるかを示します。

  3. 結果を受け取る

    question.results.finalized の webhook を登録すると、署名付きの集計結果がバックエンドに届きます。

    curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/webhooks \
  -H "X-API-Key: vz_live_…" \
  -d '{ "url": "https://example.com/hooks/votinova",
        "event_types": ["question.results.finalized"] }'

    登録時に返る signing_secret は必ず保存してください。一度しか表示されず、これがすべての配信を検証する手がかりになります。webhook ガイドには、そのまま貼り付けられる検証コードを3言語分そろえています。

うまくいかないときは

  • 401・X-API-Key ヘッダーかスコープが足りません。必要なスコープはレスポンスの required_scope に書かれています。
  • 402・ご利用のプランに API が含まれていません。解放されるプランはレスポンスの upgrade_to に書かれています。
  • 429・このウィンドウの呼び出し上限に達しました。retry_after_seconds だけ待ち、バックオフを入れて再試行してください。

次に読むもの

リファレンス全文を読み、すべてのエンドポイントをオンラインで試し、Zapier や MCP 経由でエージェントをつないでみてください。

API リファレンス →