API 概要

Cliqer API の完全なドキュメントです。REST エンドポイントと WebSocket によるリアルタイム通信を扱います。

ベース URL

すべての API エンドポイントは、接続先の Cliqer サーバーのベース URL からの相対パスです。

認証

Cliqer は、POST /api/auth/login によって発行される httpOnly の セッション Cookie（session_token）で認証します。ブラウザーはこれを自動的に送信し、サーバー間のツールでは Cookie jar に保持します。Studio 8K および Enterprise のチームは、サーバー間の REST リクエスト用に API キー を発行することもでき、Authorization: Bearer cliqer_<key> として送信します（キーの管理には Studio 8K または Enterprise プランが必要です）。WebSocket は API キーを受け付けません。セッショントークンで接続してください。

# The session cookie is set by /api/auth/login and sent on every subsequent request
Cookie: session_token=YOUR_SESSION_TOKEN

# Or authenticate a server-to-server REST request with a team API key
Authorization: Bearer cliqer_<key>

一部のエンドポイントではセッションが不要です。たとえば POST /api/licenses/validate は公開エンドポイントです。

API セクション

リクエストのライフサイクル

エラーレスポンス

すべてのエンドポイントは、標準的なエラーレスポンスを返します：

エラーレスポンスの形式：

{
  "statusCode": 400,
  "statusMessage": "Description of the error"
}

レート制限

ほとんどのエンドポイントには、クライアント IP ごとにレート制限がかかります。制限は 3 つの階層に分かれ、いずれも 60 秒の固定ウィンドウ を使用します。リクエストが上限を超えると、サーバーは Retry-After: 60 ヘッダー付きで 429 Too Many Requests を返します。段階的・指数関数的なブロックは行われず、X-RateLimit-Remaining ヘッダーも返されません。

レート制限の階層

2 つのエンドポイントでは、IP ではなく認証情報をキーとする 2 つ目の厳格制限が適用されるため、多数のアドレスから 1 つの対象に集中してリクエストを送り続けることはできません。POST /api/licenses/validate は license_key を、POST /api/auth/login はメールアドレスをキーとします。