Open API ドキュメント

TjAgentForge をお客様のシステムや AI クライアントに接続します。Open REST API (読み取り + 制御された書き込み) と MCP サーバーを提供し、どちらも同じキー、同じ実行経路、同じ監査証跡を共有します。

1. 認証

コンソールの「APIキー」ページでキーを作成し、Authorization ヘッダーで送信します。保存されるのはフィンガープリントのみ (不可逆) で、平文は作成時に一度だけ表示され、失効は即時反映されます。

Authorization: Bearer tjaf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

スコープ: read (読み取り専用) / write (制御された書き込み) / admin (このテナントのキーを管理)。allow_high_risk は独立したスイッチで、スコープではありません。

2. REST 呼び出し

読み取りエンドポイント (read スコープが必要):

curl -s https://tjagentforge.com/api/open/v1/projects \
  -H "Authorization: Bearer $TJAF_KEY"

書き込みエンドポイント (write スコープが必要):

curl -s -X POST "https://tjagentforge.com/api/open/v1/tunings/$TUNING_ID/apply" \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

すべてのレスポンスは {code, message, data} のエンベロープを使用します。code=0 は成功を意味します。

3. 制御された書き込み: Open API が自動化レベルを引き上げることはありません

既定のレベルでは、書き込みは即時実行されません。API は needs_confirmation と confirm_url を返し、キーの所有者がコンソールで承認してから実行されます。テナントが full_auto の場合にのみ直接実行されます。不可逆な高リスク操作は常に拒否されます。

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "needs_confirmation",
    "action_id": "…",
    "confirm_url": "https://tjagentforge.com/dashboard/chat?s=…",
    "expires_at": "2026-01-01T00:15:00Z"
  }
}

4. MCP 連携

MCP は JSON-RPC 2.0 を話す単一の Streamable HTTP エンドポイントで、MCP 対応の任意のクライアントから利用できます (REST と同じ APIキー認証)。

ハンドシェイクとツール一覧:

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# 列出可用工具（按密钥作用域过滤）
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

ツールの呼び出し (書き込みツールも needs_confirmation を返します):

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"project.list","arguments":{}}}'

5. エラーコード

40103 — キーが無効または失効しています
40302 — スコープが不足しています
40303 — allow_high_risk が必要、または操作が不可逆なため拒否されました
42901 — レート制限またはタスク枠の枯渇 (message を参照)

6. 機械可読なコントラクト

OpenAPI 記述は Postman やクライアントジェネレーターにインポートできます (有効なキーが必要):

curl -s https://tjagentforge.com/api/open/v1/openapi.json \
  -H "Authorization: Bearer $TJAF_KEY"