共通パターン
Common Patterns のドキュメント
Common Patterns
ページネーション
一覧エンドポイントは次のクエリパラメータを受け付けます。
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
page | number | 1 | min: 1 | ページ番号（1 始まり） |
limit | number | 20 | min: 1, max: 100 | 1 ページあたり件数 |
ページネーション付きレスポンスには pagination オブジェクトが含まれます。
エラーレスポンス
すべてのエラーは一貫した JSON 形式に従います。
一般的な HTTP ステータスコード
| Status | Meaning |
|---|---|
200 OK | 成功 |
201 Created | リソースが正常に作成された |
400 Bad Request | 無効なリクエストパラメータまたはボディ（検証失敗） |
401 Unauthorized | JWT トークンが欠落または無効 |
403 Forbidden | トークンは有効だが権限拒否 |
404 Not Found | リソースが見つからない、またはアクセス不可（所有権チェック失敗） |
429 Too Many Requests | レート制限超過 |
500 Internal Server Error | 予期しないサーバーエラー |
503 Service Unavailable | デプロイのためサーバーがドレイン中；Retry-After 秒後に再試行 |
注記: セキュリティのため、サーバーは禁止リソースに 404 を使用します。404 を受け取った場合、リソースは存在するがアクセス権がない可能性があります。
Server-Sent Events（SSE）
複数のエンドポイントが Server-Sent Events（SSE） でレスポンスをストリームします。これらはイベントを段階的にプッシュする長寿命 HTTP 接続です。
レスポンスヘッダー
イベント形式
各イベントには event 名と JSON エンコードされた data ペイロードがあります。
SSE イベントタイプ
チャット / Rules ストリーミング（POST /chats/:threadId/messages、POST /rules/:threadId/messages）
| Event | Description |
|---|---|
ping | 9 秒ごとのキープアライブハートビート |
message | AI アシスタントのテキストチャンク: { "content": "<text>" } |
error | ストリームエラー: { "content": "<message>" } |
ワークフロー実行ストリーミング（POST /workflow-runs/execute/stream）
| Event | Description |
|---|---|
ping | 9 秒ごとのキープアライブハートビート |
activity-run | アクティビティ実行ステータス更新: { "content": { "workflowRunId": "...", "status": "...", ... } } |
workflow-run | ワークフロー実行ステータス更新: { "content": { "workflowRunId": "...", "status": "...", ... } } |
thinking | AI 思考トレース: { "content": "<thinking text>", "stepId": "...", "activityRunId": "..." } |
result | ワークフロー完了時の最終結果: { "success": true, "workflowRun": { ... } } |
error | 実行エラー: { "error": "...", "details": "..." } |
SSE エンドポイントへの接続
デプロイドレインの処理
サーバーがデプロイのため再起動中の場合、SSE 対応エンドポイントはストリーム確立前に 503 Service Unavailable を返します。
フォームデータ（Multipart）
ファイルアップロードや AI メッセージ送信を含むエンドポイントは、特に multipart/form-data リクエストを受け付けます。
複雑なフィールドのエンコード
フォームデータ内の JSON オブジェクトと配列は JSON エンコード文字列です。
ID と UUID
すべての公開リソース ID は UUIDv7 形式（時間ソート可能）を使用します。例:
018f4e3a-1234-7abc-8def-0123456789ab
内部 ID（bigint）は API レスポンスでは公開されません。
タイムスタンプ
すべてのタイムスタンプは ISO 8601 文字列で返されます。
"2024-01-15T10:30:00.000Z"
検索
search をサポートする一覧エンドポイントは、リソース名フィールドに対して大文字小文字を区別しない部分一致検索を行います。