> ## 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 で API を探索する

> AI Helpdesk API は読み取り専用の REST API です。AI コーディングアシスタントと組み合わせることで、セッション・ナレッジ・手順書の探索や運用支援を効率化できます。

## AI との連携

AI Helpdesk API は OpenAPI 3.1 で記述されており、AI コーディングアシスタントが API の構造と機能を理解しやすい形式になっています。以下のようなユースケースに対応できます。

* 自然言語でのデータ抽出（「未対応のセッションを教えて」など）
* セッションの傾向分析・要約レポートの自動生成
* ナレッジ記事や手順書を AI Agent が参照するワークフローの構築

## AI 開発者向けリソース

### OpenAPI スキーマの利用

最新の OpenAPI 仕様は以下の URL から取得できます。

```text theme={null}
https://assist.i.moneyforward.com/api/v1/openapi.json
```

このスキーマを AI コーディングツール（Claude Code、Cursor、Devin など）に渡すと、エンドポイントやパラメータを理解した上でクライアントコードを生成できます。

### 自然言語インターフェースの構築

AI を使って自然言語で AI Helpdesk のデータにアクセスするインターフェースを構築できます。リードオンリーの API なので、参照系ユースケースに特に向いています。

例:

* 「未対応のセッションを 10 件教えて」
* 「過去 7 日間のクローズ済みセッションを担当タイプ別に集計して」
* 「`onboarding` カテゴリのナレッジ記事を一覧して」

### コード生成

AI を使って、自然言語の指示から API リクエストコードを生成できます。

1. 指示を自然言語で記述
2. AI が `/api/v1/sessions` や `/api/v1/knowledge` など対応するエンドポイントを特定
3. `X-API-Key` 付きの実行可能なリクエストコードを生成

## ベストプラクティス

### セキュリティ

* AI ツールに API キーを直接渡さない（環境変数経由で読ませる）
* AI 生成コードのセキュリティレビューをする
* 不要な権限を持つ API キーの作成を避ける（ADMIN ロールは必要なときだけ付与）

### エラーハンドリング

* AI 生成コードでも `{"ok": false, "error": ...}` の形式を前提にハンドリングを実装する
* 上流のスループットを圧迫しないように、リクエスト頻度を制御する（1 キーあたり `~20 RPS` 以下）

### データプライバシー

* セッション本文や個人を特定できる情報は AI ツールへ渡す前にマスキングする
* 機密情報を扱う場合は、AI ツールのデータ保持ポリシーを確認する

## サンプルユースケース

### 日次レポート生成

```python theme={null}
# AI に指示: "未対応・対応中のセッションを担当タイプ別に要約して"
# 1. /api/v1/sessions/stats でステータス別件数を取得
# 2. /api/v1/sessions?status=open でリストを取得
# 3. AI が自然言語のサマリを生成
```

### ナレッジカバレッジ分析

```python theme={null}
# AI に指示: "未解決セッションが参照しているはずなのに無いナレッジを推測して"
# 1. /api/v1/sessions?status=open で対象セッションを取得
# 2. /api/v1/knowledge で既存ナレッジを取得
# 3. AI がギャップを分析
```

## サポート

AI との連携に関する質問や問題がある場合は、サポートチームにお問い合わせください。