API の概要

RolChat のすべての REST エンドポイントは1つの規約に従います。同じベース URL、同じレスポンスエンベロープ、同じページネーション、同じエラーの形式です。一度覚えれば、エンドポイントリファレンスのすべてのエンドポイントファミリーを同じように読めます。

ベース URL とバージョニング

https://api.rolchat.com/api/v1/

バージョンはパスに含まれます。任意のフィールド、新しいエンドポイント、既定値を持つ新しいクエリパラメーターの追加は破壊的変更ではなく、バージョンは上がりません。破壊的変更は v2 としてリリースされ、非推奨となった v1 のエンドポイントは告知から少なくとも6か月間は動作し続けます（非推奨化を参照）。

認証

方式	ヘッダー	用途
JWT ベアラー	Authorization: Bearer <access_token>	対話型のセッション（ウェブアプリ、モバイルアプリ）
API キー	Authorization: Bearer rcp_<secret>	マシン間の呼び出し、プラグインの API キー
HMAC 署名	X-RolChat-Signature: sha256=…	自社システムからの受信 Webhook。Webhook を参照
なし	-	公開ウィジェットのエンドポイント（/widget/…、/forms/…）。サイトとオリジンで範囲が限定されます

連携には API キー（個人アクセストークン）を使います。キーは 設定 → プラグイン → RolChat API キー で作成し、一度だけ表示され、ハッシュとしてのみ保存されます。キーは作成したメンバーの権限を超えることはできません。呼び出しのたびに、キーのスコープがそのメンバーの現在の権限と照合されます。JWT の有効期間、X-Account-Id ヘッダー、複数の会社をまたぐセッションについては認証を参照してください。

レスポンスエンベロープ

単一のリソース:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

リスト:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

本文のないレスポンス（削除後の 204 No Content）にも、X-Request-Id ヘッダーが付きます。

エラー:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code は機械で読み取れる snake_case の値で、分岐に使うのはこの値です。message は英語で、ログ用です。field と details は役立つ場合に含まれ、個人データを含むことはありません。API が errors 配列付きで 200 を返すことはありません。エラーがある場合、ステータスは 400 以上です。コードの完全な一覧はエラーのページにあります。

ページネーション

件数が増える可能性のあるリストのエンドポイントは、カーソルページネーションを使います。最初のページはカーソルなしで要求し、その後は受け取った next_cursor をそのまま渡します。

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

• limit の既定値は50、上限は200です。それより大きい値は 400 validation_failed で拒否されます。
• カーソルは不透明な値で、24時間で失効します（code: cursor_expired 付きの 400 validation_failed）。
• 結果は最初のページで取得したスナップショットに対して一貫しています。ページの取得の間に削除されたレコードは消え、新しいレコードはカーソルなしで最初からやり直したときにだけ表示されます。
• rel="next" と rel="prev" を含む Link ヘッダーも、それを好むクライアントのために送信されます。

冪等性

POST、PATCH、DELETE には Idempotency-Key ヘッダー（UUID または ULID、255文字まで）を付けて送信します。

• キー付きの最初のリクエストは実行され、そのステータスと本文が24時間保存されます。
• 同じキーかつ同じ本文で繰り返すと、副作用を再実行せずに保存済みのレスポンスが返されます。
• 同じキーで異なる本文を送ると、409 idempotency_key_conflict で拒否されます。

副作用を伴う作成を行うすべての呼び出しで使ってください: メッセージ、メール、SMS の送信、発信、課金を伴うあらゆる操作。GET リクエストは常に冪等で、このヘッダーは無視されます。

レート制限

制限は1分あたりで数えられ、アカウント、API キー、またはユーザー単位で適用されます（サインイン不要のルートでは IP アドレス単位）。既定の上限:

バケット	既定の上限	1分あたり
サインインなしのリクエスト（IP ごと）	60	IP ごと
サインイン済みユーザー（ダッシュボード）	1 000	ユーザーごと
API キー	1 000	キーごと
公開ウィジェットのエンドポイント	訪問者ごとに60、ネットワークアドレスごとに600	1分あたり
サインイン（/auth/login）	5	IP ごと
受信 Webhook	300	1分あたり
MCP サーバー	600	1分あたり
OAuth エンドポイント	600	1分あたり

上限はプラットフォームの既定値で、運用者が変更できます。プランによって倍増することはなく、エンタープライズの上限は契約で取り決めます。レート制限のあるエンドポイントは次を返します。

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

上限を超えると、レスポンスは errors 配列に code: rate_limited を含む 429 となり、秒単位の Retry-After ヘッダーが付きます。次の呼び出しまでその時間だけ待ってください。サインインに10回失敗すると、アカウントは30分間ロックされます。

サイズとタイムアウト

カテゴリー	リクエスト本文の上限	サーバーのタイムアウト
既定	1 MB	30 秒
添付ファイル付きメッセージ	25 MB	30 秒
CSV インポート	50 MB	202 を返し、バックグラウンドで実行
ナレッジベースの画像	10 MB	30 秒
一括 API	10 MB	30 秒
検索	1 MB	10 秒
AI リクエスト	1 MB	60 秒
ウィジェットのエンドポイント	100 KB	30 秒

サイズを超える本文には 413 payload_too_large が返ります。上流がタイムアウトした場合は code: upstream_timeout 付きの 504 が返り、再試行が有効な場合は retry_after のヒントが含まれます。

コンテンツタイプ、日付、ID

• リクエストとレスポンスは application/json; charset=utf-8 です。ファイルのアップロードには multipart/form-data を使い、CSV エクスポートは text/csv を返します。不正な UTF-8 は 400 validation_failed で拒否されます。
• タイムスタンプはミリ秒精度の UTC による ISO-8601 形式です: 2026-04-20T14:23:45.123Z。入力では任意の ISO-8601 オフセットを受け付け、UTC に正規化します。
• 識別子は不透明な ULID または UUID です。数値の ID はなく、メールアドレスや電話番号が URL に含まれることはありません。

テナントの分離と権限

認証済みのリクエストはすべて1つのアカウント内で実行されます。別のアカウントに属するリソースや、呼び出し元の役割の範囲外のサイトに属するリソースには、403 ではなく 404 not_found が返されます。これにより、レコードの存在が漏れることはありません。必要な権限（例: contacts.delete）を持たない有効なトークンには 403 forbidden が返されます。一部の権限には範囲のサフィックス（conversations.read:own、:team、:all）があり、リストが返す内容を絞り込みます。

PATCH は書き込み可能なフィールドのみを受け付けます。id、account_id、created_at、updated_at、および resolved_at などの状態フィールドは読み取り専用で、これらを送ると details.forbidden_fields 付きの 400 validation_failed が返されます。状態の変更は POST /tickets/:id/resolve などの専用アクションで行います。

すべての書き込みはアカウントの監査ログに記録されます。

可観測性のためのヘッダー

すべてのレスポンスには次のヘッダーが付きます。

X-Request-Id: req_01HK…

X-Request-Id をログに記録してください。サポートが最初に尋ねるのがこの値です。

CORS

ブラウザのダッシュボードのオリジンは https://app.rolchat.com です。公開ウィジェットのエンドポイントは、任意のオリジン、またはサイトで検証したオリジンのみを許可します。API キーを使ったサーバー間の呼び出しには CORS は適用されません。

非推奨化

1. 変更は変更履歴で告知され、対象のエンドポイントは Deprecation: true と、削除日を示す Sunset ヘッダーの送信を開始します。
2. 公開エンドポイントは告知から少なくとも6か月間は動作し続けます。
3. 削除は新しいメジャーバージョンでのみ行われます。v1 の中での変更は追加のみです。

ヘルスチェック

すべてのサービスは /healthz（生存確認）と /readyz（準備完了確認）を公開しています。