Public API

ⓘ

この機能をご利用いただける方

Pro または Plus プランの admin は、Settings → General → Manage keys でスコープ付き API キーを作成できます。
操作によっては、対象機能が有効であり、利用中のプランで提供されている必要があります。スコープを付けるだけでは利用できません。

Base URL

Public API のベース URL は https://app.chatty.net/v1 です。このリファレンスの Public API エンドポイントは、このベース URL からの相対パスです。ベース URL に含まれる /v1 を残してパスを追加し、余分な /api や /chat は付けません。例えば /settings には、ベース URL の末尾に /settings を追加してアクセスします。

Chat Conversations API は /chat パスを使う別の API です。API キーのヘッダーは共通ですが、レート制限のカウンターと旧キーの扱いは異なります。

最初のリクエストを送信する

settings:read を持つキーを作成してコピーし、サーバーで安全に保管してください。各リクエストに X-Api-Key を付けます。JSON を送信する書き込みでは、Content-Type: application/json も付けてください。

curl 'https://app.chatty.net/v1/' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'X-Api-Version: 2026-08-17'

GET / には settings:read、またはそれを含む権限が必要です。選択されたバージョンを返します。

{
  "data": {
    "version": "2026-08-17"
  }
}

ヘッダーがない場合は 401 UNAUTHENTICATED、不明または失効済みのキーでは 401 INVALID_API_KEY を返します。必要なスコープがないキーや、scopes フィールドのない旧キーでは 403 FORBIDDEN を返します。

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key is missing the 'settings:read' scope"
  }
}

バージョンを選択する

バージョンは次の優先順位で選択されます。

リクエストヘッダーの X-Api-Version。
API キーに固定されたバージョン。
基準バージョンの 2026-08-17。

現在のバージョンは 2026-08-17 です。ヘッダーには YYYY-MM-DD 形式で実在する日付を指定してください。不正な日付は 400 INVALID_API_VERSION になります。日付として有効でも、将来の日付を指定して新しいエンドポイントを有効にできるわけではありません。選択された値は GET / で確認できます。バージョン専用のレスポンスヘッダーはありません。

権限と機能の利用条件

操作	スコープ	利用条件
選択されたバージョンを取得（`GET /`）	`settings:read`	Pro または Plus で作成したスコープ付きキー
セットアップのチェックリストを取得（`GET /setup/status`）	`setup:read`	Pro または Plus で作成したスコープ付きキー
設定の読み取り・更新	`settings:read` または対象ドメインの書き込みスコープ	項目やプランの制限は Settings を参照
AI assistant に質問する	`conversations:write`	AI が有効で、利用枠が残っていること。AI への質問を参照
Webhook サブスクリプションを管理	`conversations:write`	Webhooks を参照

API キーは 1 つのストアを識別します。ストア ID を渡して別のストアに切り替えることはできません。キーを作成する前に、スコープ一覧を確認してください。

セットアップ状況を取得する

GET /setup/status には setup:read が必要です。リクエストボディやクエリパラメーターはありません。

curl 'https://app.chatty.net/v1/setup/status' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'X-Api-Version: 2026-08-17'

レスポンス例です。件数はストアによって異なります。

{
  "data": {
    "entries": 3,
    "scenarios": 1,
    "skillsOn": 2,
    "skillsTotal": 10,
    "state": "setup",
    "steps": {
      "trainingData": true,
      "instructions": true,
      "skills": true,
      "scenarios": true,
      "testAi": false
    }
  }
}

entries は active、inactive、draft のナレッジ件数、scenarios は active のシナリオ数です。skillsOn と skillsTotal は Skills のチェックリストに対応します。state は、完了した項目がなければ empty、全項目が完了して AI も有効なら live、それ以外は setup です。

このエンドポイントは 401 UNAUTHENTICATED、401 INVALID_API_KEY、403 FORBIDDEN、400 INVALID_API_VERSION、429 RATE_LIMITED、500 INTERNAL_ERROR を返す場合があります。エラーは GET / と同じ error.code と error.message の形式です。

制限とエラー

Public API の制限は、キーごとに毎分 120 リクエスト、送信元 IP ごとに毎分 300 リクエストです。認証されなかったリクエストも IP のカウンターに含まれます。POST /ai/ask には、さらにキーごとに毎分 20 リクエストの制限があります。レスポンスヘッダー、再試行間隔、AI 利用枠のエラーについては Errors and rate limits をご覧ください。

リソース別リファレンス

操作	リファレンス
メールで会話を開始し、ファイルをアップロード、返信、会話のエクスポート、または会話を削除	Public conversations
顧客プロフィール、タグ、メモリを作成・更新、または顧客データをエクスポート	Customers
ナレッジ、FAQ（インポート、エクスポート、全件削除を含む）、Scenarios、Training、同期ジョブを管理	Knowledge and training
Shortcuts と Campaigns を取得・変更	Shortcuts and campaigns
言語を追加し、公開状態やデフォルトを変更、または翻訳を編集・リセット	Languages and translations
設定、ストアの環境設定、商品のおすすめを変更	Settings and features
分析、チャットから購入へのレポート、インテント、サブスクリプション、利用状況を取得	Analytics and usage
チャンネルと連携の状況を取得、チャンネル設定の変更、連携の接続・切断	Channels and integrations
Help center の設定、ストアページ、色、アセットを取得または変更	Help center
Webhook の配信ログを取得、再配信、テスト送信	Webhooks
スタッフ、権限を委譲する API キー、AI client 接続を管理	Team and Access
AI クライアントからこれらの操作を実行	MCP tool reference

HTTP のバージョン確認（GET /）を除き、同じ操作を MCP からも実行できます。利用できるツールと action の権限は、API キーか OAuth かによって異なります。OAuth の許可を持っていても、REST を直接呼ぶ認証には使用できません。エンドポイント一覧は Quick Reference をご覧ください。

Authentication Settings and Features