> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API概要
> FIM One REST APIの開始
API リファレンスドキュメントは現在**英語のみ**で利用可能です。このページを別の言語で表示している場合は、英語版に切り替えてください。左側のサイドバーに完全なAPIエンドポイントリストが表示されます。
FIM One は、AI 智能体、会話、ナレッジベースなどへのプログラマティックアクセスのための REST API を提供します。
## ベースURL
```
https://your-domain.com/api
```
## 認証
すべてのAPI リクエストは、APIキーまたはJWTトークンを使用した認証が必要です。
### APIキーの使用
`Authorization`ヘッダーにAPIキーを含めます：
```bash theme={null}
curl -H "Authorization: Bearer fim_your_api_key_here" \
https://your-domain.com/api/agents
```
### JWT トークンの使用
SSE ストリーミングエンドポイント（`/api/react` と `/api/dag`）の場合、リクエストボディでトークンを渡すことができます：
```json theme={null}
{
"q": "What's the weather today?",
"token": "your_jwt_token_here"
}
```
詳細なセットアップ手順については、[認証](/api/authentication)を参照してください。
## レスポンス形式
### 成功レスポンス
すべての成功したAPIレスポンスは、以下の構造に従います：
```json theme={null}
{
"success": true,
"data": {
"id": "conv_123abc",
"title": "My Conversation",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### エラーレスポンス
エラーレスポンスにはエラーコードと人間が読める形のメッセージが含まれます：
```json theme={null}
{
"success": false,
"error": "conversation_not_found",
"message": "The conversation does not exist or has been deleted"
}
```
### ページネーション付きレスポンス
リストエンドポイントはページネーション付きの結果を返します:
```json theme={null}
{
"items": [
{ "id": "item_1", "name": "First Item" },
{ "id": "item_2", "name": "Second Item" }
],
"total": 42,
"page": 1,
"size": 20,
"pages": 3
}
```
## ストリーミング (Server-Sent Events)
チャットエンドポイント (`POST /api/react` と `POST /api/dag`) はリアルタイムストリーミング用の Server-Sent Events を返します。各イベントには、そのコンテンツを示す `type` フィールドがあります:
| イベントタイプ | 説明 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `step` | ReAct 推理ステップ (ツール呼び出し、思考)。拡張思考機能を持つモデル (Claude、o-series、DeepSeek-R1) の場合、ツール決定フェーズ中のリアルタイム `thinking_delta` コンテンツを含みます |
| `step_progress` | DAG ステップの進捗 (開始/反復/完了)。基盤となる智能体が推理トークンをストリーミングする場合、`thinking_delta` コンテンツを含む可能性があります |
| `phase` | パイプラインフェーズの遷移 (計画/実行/分析) |
| `compact` | コンテキストの圧縮が発生しました |
| `answer` | ストリーミングされた回答テキスト (開始/デルタ/完了) |
| `done` | 最終結果ペイロード |
| `suggestions` | 提案されたフォローアップ質問 |
| `title` | 自動生成された会話タイトル |
| `end` | ストリーム終了記号 (常に最後) |
### SSE ストリーム例
```
event: step
data: {"type": "tool_call", "tool": "search", "input": "Paris weather"}
event: answer
data: {"type": "delta", "text": "Based on current data, "}
event: answer
data: {"type": "delta", "text": "Paris has pleasant weather."}
event: done
data: {"answer": "Based on current data, Paris has pleasant weather.", "tokens": 128}
event: suggestions
data: ["What about tomorrow's forecast?", "Compare with other European cities"]
event: end
data: {}
```
### カーソルベースの再開
すべてのSSEイベントには、会話にスコープされた単調な`cursor`整数が含まれます。クライアントは最も高いカーソルを追跡する必要があります。接続がターン中に切断された場合（ネットワークエラー、プロキシタイムアウト、サーバー再起動）、クライアントはエージェントを再実行せずに再度サブスクライブできます：
```http theme={null}
POST /api/chat/resume
Content-Type: application/json
Authorization: Bearer
{
"conversation_id": "",
"cursor": 42
}
```
レスポンスはSSEストリームで、`cursor > 42`のキャッシュされたイベントを再生し、ターミナル`event: resume_done`フレームで終了します。`cursor: -1`を渡して、最初からの完全な再生をリクエストします。
エラーレスポンス：
* `404 conversation_not_found` — 会話IDが無効であるか、認証されたユーザーが所有していない
* `404 no_recent_assistant_message` — 会話に再開するための永続化されたアシスタントターンがない（例：ユーザーメッセージがない新しい会話）
* `400 invalid_cursor` — カーソルが非負の整数または`-1`ではない
リファレンスフロントエンド実装（プレイグラウンドの`useSseResume`フック）は、ネットワーク切断を指数バックオフ（300ms → 1s → 3s、最大3回の試行）で自動再試行し、ユーザーが開始した中止とネットワークエラーを区別して、意図しない再接続を回避します。完全なパターンについては、`playground-page.tsx`統合を参照してください。
再開はステートレスです — アシスタントメッセージの保存された`sse_events`配列から再生します。エージェントのターンがアシスタントメッセージが永続化される前に中断された場合（例：`done`の前のクラッシュ）、ぶら下がった`tool_use`ブロックは次のターンで`DbMemory._repair_dangling_tool_calls`によって自動修復されます。合成`tool_result`行は`metadata_.synthetic=true`および`metadata_.reason="interrupted"`で永続化され、監査用に使用されます。
## レート制限
キーごとのレート制限は将来のリリースで予定されています。現在、キーごとのリクエスト制限は強制されていませんが、APIを責任を持って使用してください。
## ページネーション
リストエンドポイントはクエリパラメータを使用したページネーションをサポートしています：
```bash theme={null}
curl "https://your-domain.com/api/conversations?page=2&size=50" \
-H "Authorization: Bearer fim_your_api_key_here"
```
パラメータ：
* `page` (デフォルト: 1) — ページ番号、1から始まります
* `size` (デフォルト: 20) — ページあたりのアイテム数、最大 100
## タイムスタンプ
すべてのタイムスタンプはUTCタイムゾーン付きのISO 8601形式です:
```json theme={null}
{
"created_at": "2024-01-15T10:30:45.123456Z",
"updated_at": "2024-01-15T14:22:10.654321Z"
}
```
## エラーコード
一般的なエラーコードとその意味：
| エラーコード | HTTPステータス | 意味 |
| --------------------- | --------- | -------------------- |
| `unauthorized` | 401 | 無効または欠落している認証 |
| `forbidden` | 403 | このリソースへのアクセス権限がありません |
| `not_found` | 404 | リソースが存在しません |
| `bad_request` | 400 | 無効なリクエストパラメータ |
| `rate_limit_exceeded` | 429 | リクエストが多すぎます（予定） |
| `internal_error` | 500 | サーバーエラー |
## API プレイグラウンド
各エンドポイントページには、以下のことができるインタラクティブな API プレイグラウンドが含まれています:
* ブラウザから直接リクエストをテストする
* 実際のレスポンスを表示する
* 複数の言語でリクエストコードをコピーする
* API キーで認証する
API プレイグラウンドはブラウザからリクエストを実行するため、API キーに適切な CORS パーミッションがあることを確認してください (通常、同一オリジンのリクエストではデフォルトで有効になっています)。
## SDK の利用可能性
FIM One API は完全に REST ベースですが、一般的なプログラミング言語で SDK が利用可能です (またはまもなく利用可能になります):
* **Python**: 近日公開予定
* **JavaScript/TypeScript**: 近日公開予定
* **Go**: 近日公開予定
## バージョニング
現在のAPIバージョンは `v0.8.0` です。バージョンはURLパスに含まれていません。破壊的な変更はメジャーバージョンのバンプと移行期間を通じて通知されます。
## サポート
API の問題または質問については:
* **ドキュメント**: 各エンドポイントの詳細ガイドを参照してください
* **GitHub Issues**: バグを報告してください [https://github.com/fim-ai/fim-one/issues](https://github.com/fim-ai/fim-one/issues)
* **Discord コミュニティ**: コミュニティに参加して議論してください