開発者API

外部システムや社内ツールと連携するための API キーの発行・管理は、管理画面の「設定」→「開発者API」から行います。この画面は管理者にだけ表示されます。

APIキーの一覧には、名前・種別・権限・有効期限・最終使用・状態が並びます。この画面で発行するのはサービスキーで、指定した有効期限まで使えます。CLI のログインで発行される個人キーは最長 12 時間です。

通話の API で電話番号を指定すると、その番号へ電話網（PSTN）から発信します。電話番号を指定しない場合は、ブラウザ用の Webコールになります。

各エンドポイントのパス・パラメータ・レスポンス・エラー・curl の例は「API リファレンス」にまとめています。

CLI を使うCopy Anchor Link

kumion CLI は、ターミナルから同じテナントのエージェントや通話履歴を操作するための道具です。

インストールCopy Anchor Link

Node.js 20.18.1 以上が入っているパソコンで、ターミナルから次を実行します。

npm i -g @kumion/cli

インストールできたかは kumion --version で確認できます。使えるコマンドの一覧は kumion --help で見られます。

よく使うコマンドCopy Anchor Link

ログインしたあと（手順は次の「ブラウザで承認する」）、次のコマンドが使えます。表示の詳しい書式は kumion --help でご確認ください。

• kumion agents list：テナントのエージェントを一覧表示します。
• kumion templates list：エージェントのひな形（テンプレート）と ID を一覧表示します。
• kumion agents create-from-template --template ID --business-name 店名：ひな形から下書きのエージェントを作ります。--url（同じサイトの最大10ページ）または --document 資料ID（抽出まで終わった資料）を付けると、資料に書かれている事実だけが入ります。何も付けなければ、すべて「まだない情報」です。公開はされず、確認済みの事実もありません。--idempotency-key を付けると、同じ操作を再送しても最初のエージェントが返ります。agents:write の権限が必要です。
• kumion agents get エージェントID：エージェントの下書きと公開中のバージョンを表示します。
• kumion agents spec エージェントID --version 版 --format 形式 --out 保存先：エージェントの応対内容をまとめた仕様書を、ファイルとして保存します。--version は published（公開中。省略時）・draft（下書き）・版番号（1、2 …）から選びます。--format は pdf（省略時）・docx・markdown です。--out を付けるとそのパスに保存します。付けないときは、PDF と Word はサーバーが付けたファイル名でカレントディレクトリに保存し、Markdown は画面に出力します。agents:read の権限が必要です。
• kumion flow get エージェントID：下書きのフローを、キャンバスのアシスタントと同じ形（用件、言い方、聞く項目）で表示します。転送できるスタッフと、公開前の指摘も出ます。
• kumion flow update エージェントID --revision リビジョン番号 --patch-file ファイル：用件ごとの言い方・条件・聞く項目と、スタッフへの転送を直します。
• kumion flow edit-steps エージェントID --revision リビジョン番号 --ops-file ファイル：ステップごとに組んだフローで、ステップの追加・削除、つなぎ方、各ステップの設定をまとめて直します。1 件でも断られると何も保存されません。
• kumion staff list／kumion staff create／kumion staff update：転送先になるスタッフを一覧・登録・変更します。staff update の変更は公開しなくても次の通話から使われます。
• kumion contacts list（MCP: list_contacts）：お客様を一覧。必要な権限は contacts:read です。
• kumion contacts get（MCP: get_contact）：お客様1件を電話番号つきで表示。必要な権限は contacts:read です。
• kumion contacts create（MCP: create_contact）：お客様を登録。必要な権限は contacts:write です。
• kumion contacts update（MCP: update_contact）：お客様を変更。必要な権限は contacts:write です。
• kumion contacts calls（MCP: list_contact_calls）：お客様にひもづく通話を一覧。必要な権限は contacts:read です。
• kumion contact-fields list（MCP: list_contact_fields）：お客様のカスタム項目の定義を一覧。必要な権限は contacts:read です。
• kumion calls link-contact（MCP: link_call_contact）：通話の発信者番号をお客様にひもづけ。必要な権限は calls:write です。
• kumion call-marks list（MCP: list_call_marks）：通話のマークとマーク種別を一覧。必要な権限は calls:read です。
• kumion call-marks set（MCP: set_call_mark）：通話にマークを付ける。必要な権限は calls:write です。
• kumion call-marks clear（MCP: clear_call_mark）：通話のマークを外す。必要な権限は calls:write です。
• kumion call-marks create-type（MCP: create_call_mark_type）：マーク種別を追加。必要な権限は calls:write です。
• kumion callback-lists create（MCP: create_callback_list）：通話から折り返しリストの下書きを作成（発信はしません）。必要な権限は calls:write です。
• kumion captures list（MCP: list_captures）：通話中に記録された要約を一覧。必要な権限は captures:read です。
• kumion captures update（MCP: update_capture）：要約の対応状況とメモを変更（担当者は画面で設定）。必要な権限は captures:write です。
• kumion captures status-log（MCP: get_capture_status_log）：要約の対応状況の変更履歴。必要な権限は captures:read です。
• kumion documents history（MCP: get_document_history）：資料のバージョン履歴。必要な権限は agents:read です。
• kumion documents version-diff（MCP: get_document_version_diff）：資料の2つのバージョンの差分。必要な権限は agents:read です。
• kumion documents rollback（MCP: rollback_document）：資料を以前のバージョンに戻す（公開せずに次の通話から使われます）。必要な権限は agents:live です。
• kumion analytics get（MCP: get_analytics）：分析画面の数値。必要な権限は analytics:read です。
• kumion hours get／kumion hours update／kumion hours exception set：店舗の営業時間・定休日・例外日を表示・変更します。hours get が出したリビジョン番号を --revision に渡してください。hours update の営業時間と定休日は、渡した内容で全体を置き換えます（渡さなかった項目はそのままです）。例外日は --kind closed|open|inherit で指定し、inherit はその日だけの設定を消して週のルールに戻します。変更は公開せずに次の通話から使われます。
• kumion booking get エージェントID／kumion booking calendar update／kumion booking services create／kumion booking services update：予約の受け付け方（1 枠の長さ・受付の締め切り・何日先まで）と、予約メニューを表示・変更します。booking get が出したリビジョン番号を --revision に渡してください。枠の長さは 1〜1,440 分、受付の締め切りは 0〜43,200 分、先の日数は 1〜730 日です。メニューの所要時間に null を渡すと、枠の長さを使います。メニューの追加もリビジョン番号を取るので、同じ番号で同時に追加しても通るのは 1 件だけです。変更は公開せずに次の通話から使われます。
• kumion agents patch エージェントID --revision リビジョン番号 --prompt-file ファイル：プロンプト、またはフロー全体を置き換えます。
• kumion agents opening-name エージェントID --revision リビジョン番号 --on|--off：最初のあいさつで、かけてきた人の名前を呼ぶかどうかを切り替えます。下書きの変更なので、次の公開から通話に反映されます。
• kumion agents availability エージェントID --revision リビジョン番号 --operating-hours-file ファイル --off-hours-file ファイル：受付時間と、受付時間外の通話の扱いを設定します。ファイルにはその設定の JSON を入れ、null を入れると設定を消します。公開しなくても次の通話から使われます（agents:live の権限が必要です）。
• kumion agents publish エージェントID：公開前チェックを通して公開します。チェックが通らないと何も公開されず、失敗したケースが表示されます。ケースが再実行でも失敗した（[reproduced]）ときは、飛ばす方法はありません。直してから、もう一度テストして公開します。再実行のうち一部だけ失敗した（[intermittent]）ときは、ほかに問題がなければ、CLI が各回の理由を並べて表示します。それを確認したうえで、リスクを受け入れる場合に限り --accept-intermittent を付けると公開できます。毎回失敗したケースには使えません。MCP では acceptIntermittent です。
• kumion test-runs start エージェントID：下書きに対して回帰テストを実行し、結果が出るまで待ちます（全件通ったときだけ終了コードが 0 です）。--no-wait を付けると待たずに戻ります。
• kumion test-runs start エージェントID --turns ファイル：実際の通話で失敗した来電者の台詞を、そのまま下書きに流して再現します。ファイル（- なら標準入力）には ["台詞", ...] または [{ "caller": "台詞" }, ...] の JSON を入れます。台詞は 30 句まで、1 句 500 文字まで、合計 6,000 文字までです（超えると replay_too_long）。台詞は順に 1 句ずつ流れ、合否の判定はしません。結果は、会話・通ったノード・呼んだツール・トレースです。台詞を流し終えたとき、またはエージェントが先に通話を終えたときに終了コードは 0 です。台詞には実際の通話の内容が含まれることがあります。結果はテスト実行に残り、保持期間は通常のテスト実行と同じです。通話履歴には残らず、通話の回数にも数えません。
• kumion test-runs get エージェントID 実行ID／kumion test-runs list エージェントID：実行結果と、実行の履歴を表示します。[intermittent] のケースには、各回の結果も出ます。いずれも tests:run の権限が必要です。
• kumion calls create エージェントID --var 名前=値：通話を始めます。--var は何度でも指定でき、値は「通話ごとの変数」として使えます。
• kumion calls create エージェントID --to 08012345678：Webコールの代わりに、その電話番号へ実際に電話をかけます。相手に表示される発信者番号は、エージェントに割り当てた番号です。結果（応答あり・話し中・応答なし・発信失敗）は kumion calls get 通話ID の disposition で確認します。
• kumion calls list：通話履歴を新しい順に一覧表示します。--agent・--channel・--from・--to・--search で絞り込めます。
• kumion calls get 通話ID：1 件の通話の情報（かかってきた経路・着信／発信・電話番号・時刻・終わり方）を表示します。direction は通話に保存された元の値（inbound・outbound・on_net）、portalDirection は管理画面の通話履歴と同じ着信（inbound）／発信（outbound）の区分です（どちらでもない通話は null）。着信・発信の件数は portalDirection で数えてください。
• kumion calls transcript 通話ID：通話の文字起こしを表示します。
• kumion scheduled-calls create エージェントID --to 電話番号 --at 日時：指定した時刻に、1 回だけ電話をかけます。--at には時差つきの日時（例 2026-10-31T13:00:00+09:00）を未来の時刻で指定します。自動の再ダイヤルはありません。テナントの自動発信がオフのとき、またはフリープランのときは受け付けられません。--var 名前=値 も付けられます。
• kumion scheduled-calls list／kumion scheduled-calls cancel ID：この方法で予約した発信を一覧し、まだ始まっていないものを取り消します。

flow update、flow edit-steps、agents patch、agents opening-name が書き換えるのは下書きだけです。通話に使われるのは agents publish で公開したあとです。flow update、flow edit-steps と、営業時間・予約設定・資料の書き換えには --dry-run があり、付けると変わる内容だけを表示して保存しません（agents patch と staff・facts の書き換えには --dry-run はありません）。

公開せずに次の通話から使われる書き換え（agents availability、staff update、営業時間、予約設定、facts edit|confirm、記録項目、資料の差し替え）には、agents:live の権限が必要です。権限が足りないコマンドは、必要な権限の名前を添えてエラーになります。

通話を読むコマンド（calls list、calls get、calls transcript、scheduled-calls list）には、通話履歴を読む権限（calls:read）が必要です。ログインの承認画面で、この権限を外さないでください。通話を始める・予約するコマンドは calls:create です。

出力を JSON で受け取りたいときは、コマンドに --json を付けます。

CLI／MCP でできることCopy Anchor Link

上のコマンドと同じ操作は、すべて MCP ツールからも使えます（kumion mcp。AI アシスタントから使うときの接続方法です）。API キーだけでも、次の設定まで終わらせられます。

• 資料のアップロードと差し替え：kumion documents upload で、資料のテキストまたはファイル（.txt / .md / .pdf / .docx / .xlsx、10ファイル・20MiBまで）を送り、kumion documents jobs get で抽出の完了を待ち、kumion documents get 資料ID で抽出された項目を確認します。抽出は1キーあたり1時間10回、同時に1件までです。--dry-run を付けると、送らずに文字数・使うモデル・残りの回数を確認できます。抽出した資料は kumion documents replace で、テンプレートから作ったエージェントの資料と差し替えられます。エージェントの ID は変わらず、項目はすべて未確認に戻るので、kumion facts list エージェントID で一覧を見て、kumion facts edit で値を直し、kumion facts confirm でまとめて確認し直します。
• 営業時間：kumion hours get で今の設定とリビジョン番号を見て、kumion hours update で営業時間と定休日を、kumion hours exception set で臨時休業・振替出勤を決めます。
• 予約設定：kumion booking get で今の設定を読み、kumion booking calendar update（1枠の長さ・直前予約の締め切り・何日先まで）、kumion booking services create|update（予約できる内容）、kumion booking resources create|update（担当と予約枠）を設定し、kumion booking mount でそのエージェントの予約受付を始めます。kumion booking slots は、通話と同じ計算で空き枠を確認します（予約は取りません）。
• 記録項目：kumion capture-specs list|create|update で、通話のあとに記録する項目を作り・直し、kumion agents capture set でエージェントに紐づけます。kumion agents capture get は、そのエージェントが記録できる状態かどうかも返します。
• 仕様書：kumion agents spec／MCP の get_agent_spec で、エージェントの設定をまとめた仕様書を保存します。版は published（省略時）・draft・版番号、形式は pdf（省略時）・docx・markdown から選べます。MCP では、PDF と Word は保存先のパス（outputPath）を指定する必要があり、Markdown は本文がそのまま返ります。agents:read の権限が必要です。

これらの変更は、保存すると次の通話から使われます（公開は不要です）。--dry-run を付けたコマンドは、変わる内容だけを表示して保存しません。書き換えるコマンドは、直前に読んだリビジョン番号を --revision に渡してください。番号が古いと、何も保存されずにエラーになります。

ブラウザで承認するCopy Anchor Link

管理者だけが承認できます。

1. ターミナルで kumion auth login を実行します。
2. 表示されたページを、管理画面にログイン済みのブラウザで開きます。画面の題は「CLIのログイン」です。
3. 「確認コード」が、ターミナルに出ているコードと同じか確かめ、「確認」をクリックします。コードには期限があります。ターミナルに残りの分数が出ます。
4. 「テナント」で、管理者になっているテナントを選びます。管理者のテナントがないときは「管理者になっているテナントがありません」と出ます。
5. 「権限」で、CLI が求めた権限を確認します。不要なものは外せます。組織のキーポリシーで許可されていない権限は選べません。
6. 「承認する」をクリックします。「承認しました。ターミナルに戻ってください。」と出たら、ターミナル側のログインは完了です。

ご自身で kumion auth login を実行した場合だけ承認してください。承認すると、そのターミナルはあなたの権限でテナントを操作できるようになります。心当たりがないコードは「拒否する」をクリックします。

発行されるのは個人キーです。最長 12時間 で失効します。組織のキーポリシーでより短い上限があるときは、画面にその時間が出ます。期限が切れたら、もう一度 kumion auth login を実行します。あなたがこのテナントの管理者でなくなった時点でも、キーは使えなくなります。

キーの保存場所Copy Anchor Link

個人キーは、お使いの OS のキーチェーンにだけ保存されます。ファイルには書きません。

• macOS：キーチェーン
• Windows：資格情報マネージャー
• Linux：Secret Service

テナントや接続先などのプロファイル名は、次のファイルに残ります。キーそのものは入りません。

• macOS と Linux：~/.config/kumion/config.json
• Windows：%APPDATA%\kumion\config.json

いまのログイン状態は kumion auth status で確認できます。キーの種類と失効時刻が出ます。

ログアウトCopy Anchor Link

kumion auth logout を実行すると、そのプロファイルとキーチェーン上のキーが削除されます。名前を付けたプロファイルのときは kumion auth logout --profile 名前 です。

開発者APIのキーで入る場合Copy Anchor Link

「開発者API」で発行したサービスキーでもログインできます。ターミナルで kumion auth login --with-api-key を実行し、テナントIDとキーを入力します。テナントIDは、管理画面のURL（/tenants/ の次）と、開発者APIの画面にある例で確認できます。このキーもキーチェーンに保存され、ファイルには書きません。個人キーとは違い、画面で指定した有効期限まで使えます。