> ## Documentation Index
> Fetch the complete documentation index at: https://hc.saas-manager.biz.nuro.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# ページング

> AI Helpdesk API の一覧取得エンドポイントは `limit` パラメータで取得件数を制御します。カーソルやページ番号は使用しません。

## 取得件数の指定

一覧取得系のエンドポイントは `limit` クエリパラメータで取得件数を制御します。`limit` の上限と既定値はエンドポイントごとに異なります。

| エンドポイント                     | 既定値 | 最大値 |
| --------------------------- | --- | --- |
| `GET /api/v1/sessions`      | 50  | 100 |
| `GET /api/v1/knowledge`     | 50  | 100 |
| `GET /api/v1/procedures`    | 200 | 500 |
| `GET /api/v1/notifications` | 20  | 100 |

`page` / `offset` / `cursor` のような追加のページングパラメータはありません。次ページ取得用のトークンも返しません。

## レスポンス形式

一覧取得エンドポイントは、リソース配列と件数を含むレスポンスを返します。

```json theme={null}
{
  "ok": true,
  "sessions": [
    // セッションの配列
  ],
  "count": 23
}
```

### レスポンスフィールド

| フィールド                                                                     | 型       | 説明                             |
| ------------------------------------------------------------------------- | ------- | ------------------------------ |
| `ok`                                                                      | boolean | 成功時 `true`                     |
| `sessions` / `articles` / `procedures` / `notifications` / `integrations` | array   | 取得したリソースの配列（エンドポイントによりキー名が異なる） |
| `count`                                                                   | integer | このレスポンスに含まれるリソースの件数            |

`count` は **このレスポンスに含まれる件数** であり、テナント全体の総件数ではありません。

## フィルタ

一覧取得エンドポイントは、リソースに応じて以下のクエリパラメータでフィルタできます。

### `GET /api/v1/sessions`

| パラメータ          | 値                                                        | 説明         |
| -------------- | -------------------------------------------------------- | ---------- |
| `status`       | `open` / `in_progress` / `pending_approval` / `resolved` | ステータスで絞り込み |
| `assigneeType` | `unassigned` / `ai_agent` / `human_agent` / `requester`  | 担当タイプで絞り込み |

### `GET /api/v1/knowledge`

| パラメータ      | 説明        |
| ---------- | --------- |
| `category` | カテゴリで絞り込み |
| `type`     | 種別で絞り込み   |

<Info>
  **`assigneeType` と `type` フィルタの注意点**

  `assigneeType`（sessions）と `type`（knowledge）は **DynamoDB から `limit` 件取得した後にメモリ上で絞り込みます**。そのため、これらのフィルタを指定した場合の `count` は「最初の `limit` 行のうちマッチした件数」であり、テナント全体の総件数ではありません。

  全件取得が必要な場合は、これらのフィルタを指定せずにすべてを取得し、クライアント側で絞り込んでください。
</Info>

## 使用例

### cURL での使用例

```bash theme={null}
# デフォルトの 50 件を取得
curl -H "X-API-Key: YOUR_API_KEY" \
  https://assist.i.moneyforward.com/api/v1/sessions

# 100 件まで取得
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://assist.i.moneyforward.com/api/v1/sessions?limit=100"

# 未対応セッションのみ
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://assist.i.moneyforward.com/api/v1/sessions?status=open"
```

### JavaScript での使用例

```javascript theme={null}
async function fetchSessions({ status, limit = 50 } = {}) {
  const params = new URLSearchParams();
  if (status) params.set('status', status);
  params.set('limit', String(limit));

  const response = await fetch(
    `https://assist.i.moneyforward.com/api/v1/sessions?${params}`,
    {
      headers: {
        'X-API-Key': 'YOUR_API_KEY'
      }
    }
  );

  return response.json();
}
```

## ベストプラクティス

1. 必要以上に大きな `limit` を指定しないでください。レスポンスサイズと処理時間に影響します。
2. `assigneeType` や `type` フィルタを使う場合、`count` が部分的な値である点に注意してください。全件確認が必要なときはフィルタなしで取得してクライアント側で絞り込みます。
3. 一覧取得を繰り返す場合は、上流のスループットを圧迫しないように間隔を空けてください（目安: 1 つの API キーで `~20 RPS` 以下）。