Flauro Public API リファレンス

フロントエンドは本 API を組み込むだけで、いま使っているツールに生成 AI の品質と統制を取り込めます。認証は Bearer トークン、レスポンスはすべて JSON。全応答に traceId が付与され、追跡・監査が容易です。

1. 認証

すべての業務エンドポイントは Bearer トークンが必要です。トークンは以下の 2 種類が使えます。

Authorization: Bearer <JWT または flp_...>
Content-Type: application/json

organizationId（テナント）はトークンから解決されるため、リクエストボディに含める必要はありません。

1.1 ログイン

POST/auth/login — レート制限 5 req/分。

{ "email": "you@example.com", "password": "********", "totpCode": "123456" }

• totpCode は 2 要素認証が有効なユーザーのみ必須。
• 2FA 有効で totpCode 未指定の場合は { "requiresTwoFactor": true } を返す。

{
  "access_token": "eyJhbGciOi...",
  "user": { "id": "...", "email": "...", "organizationId": "...", "role": "admin" }
}

1.2 Personal Access Token の発行

POST/auth/personal-access-tokens（要 JWT）。

{ "name": "ci-bot", "scopes": ["llm:call"], "expiresAt": "2027-01-01T00:00:00Z" }

{ "id": "...", "name": "ci-bot", "scopes": ["llm:call"], "expiresAt": "2027-01-01T00:00:00Z", "token": "flp_xxxxxxxx" }

• 一覧: GET /auth/personal-access-tokens（raw token は含まない）
• 失効: DELETE /auth/personal-access-tokens/:id

2. LLM 統一ゲートウェイ

2.1 POST /llm/call — 統一呼び出し

ガードレール・ルーティング・コスト計測を通して LLM を呼び出す中核エンドポイント。model からプロバイダを自動推論するため、1 本で OpenAI も Claude も Gemini も呼べます。

レート制限: 60 req/分/テナント。

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Flauro のアーキテクチャを要約して" }
  ],
  "model": "gpt-5.6-sol",
  "provider": "openai",
  "temperature": 0.2,
  "max_tokens": 1024,
  "reasoning_effort": "high",
  "response_format": { "type": "json_object" },
  "thinking_mode": "adaptive",
  "thinking_effort": "medium",
  "purpose": "external"
}

{
  "content": "...",
  "model": "gpt-5.6-sol",
  "costUsd": 0.00046,
  "routedTo": "openai",
  "traceId": "trace_1731490000000",
  "decisionId": "...",
  "usage": { "promptTokens": 120, "completionTokens": 340 }
}

2.2 プロバイダ互換プロキシ

既存 SDK / ツールをそのまま接続できる互換エンドポイント。いずれもゲートウェイのガードレール・コスト計測を通ります。

Base URL = https://api.flauro-dev.com/api/v1/llm/openai
API Key  = flauro の JWT または PAT

2.3 GET /llm/models — 利用可能モデル一覧

組織の設定済み API キーでフィルタしたモデルカタログを返す。

[
  { "id": "gpt-5.6-sol", "provider": "openai", "label": "GPT-5.6 Sol", "contextWindow": 256000, "capabilities": ["reasoning", "json", "vision"] }
]

主なモデル ID: gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna / gpt-5.5 / gpt-5.5-pro / gpt-4o / gpt-4o-mini / o3 / o4-mini / claude-sonnet-5 / gemini-2.0-flash / Bedrock モデル ID ほか。

2.4 GET /llm/health — サーキットブレーカ状態

{
  "status": "ok",
  "circuitState": "CLOSED",
  "failureCount": 0,
  "failureThreshold": 5,
  "localLlm": { "enabled": true, "baseUrl": "...", "model": "Qwen/Qwen2.5-7B-Instruct" },
  "checkedAt": "2026-07-13T10:00:00.000Z"
}

status: ok（CLOSED）/ degraded（HALF_OPEN）/ unavailable（OPEN）。

3. オーケストレーション（RAG × パイプライン）

RAG 検索・生成・変換を組み合わせた多段パイプラインを 1 リクエストで実行します。

なぜ RAG × パイプラインを使うのか（メリット）

素の POST /llm/call は「単発の LLM 呼び出し」です。これに対し /orchestrate は次の課題を解決します。

利用の判断基準: 自社の知識（コード/仕様/インシデント履歴）に基づいた回答が必要なら RAG を、複数段の処理を一本化したいならパイプラインを使います。単純な生成だけなら /llm/call で十分です。

3.1 POST /orchestrate — 同期 / 非同期実行

レート制限: 30 req/分。

{
  "pipeline": "software_dev/pr_review",
  "inputs": { "diff": "..." },
  "mode": "sync",
  "options": { "model": "gpt-5.6-sol", "preferLocal": false, "maxCostUsd": 0.5 }
}

{
  "steps": [
    { "id": "ctx", "type": "retrieve", "source": "repo", "query": "{input.question}", "limit": 5 },
    { "id": "gen", "type": "generate", "prompt": "コンテキスト:\n{steps.ctx.output}\n\n質問: {input.question}" }
  ],
  "inputs": { "question": "認証まわりの実装方針は？" },
  "mode": "sync"
}

• pipeline と steps はどちらか一方が必須。
• ステップ種別: retrieve（RAG 検索）/ generate（LLM 生成）/ transform（整形）。
• 変数展開: {input.*} {previousOutput} {context.<id>} {steps.<id>.output}。
• options.preferLocal: true=ローカル LLM 優先 / false=クラウド強制 / 省略=自動判断。

{
  "traceId": "...",
  "content": "{ \"summary\": \"...\", \"sources_used\": true }",
  "steps": [
    { "stepId": "ctx", "type": "retrieve", "status": "success", "resultCount": 5 },
    { "stepId": "gen", "type": "generate", "status": "success", "costUsd": 0.00046 }
  ]
}

{ "ok": true, "runId": "...", "traceId": "..." }

3.2 POST /orchestrate/stream — SSE ストリーム実行

Content-Type: text/event-stream で段階的にイベントを返す。

event: step
data: {"stepId":"ctx","type":"retrieve","status":"success","resultCount":5}

event: token
data: {"delta":"..."}

event: error
data: {"message":"...","traceId":"..."}

3.3 実行状況・パイプライン管理

3.4 RAG のセットアップ（retrieve を機能させる）

retrieve ステップは、対象データがあらかじめ索引化されていて初めて結果を返します。索引が無い場合でもエラーにはならず、resultCount: 0 で生成ステップは続行します（＝根拠なしの回答になる）。実運用では以下を設定してください。

ステップ 1: 検索ソースを選ぶ

retrieve の source で参照先を指定します。

ステップ 2: コード索引（repo）を用意する

1. 組織に GitHub 連携を設定する（Webhook を接続）。
2. 初回は対象リポジトリのフル索引を作成する（管理者向け Indexer 実行）。
3. 以降は既定ブランチへの push を契機に、変更ファイルのみ自動で増分索引される。

ステップ 3: 動作確認

生成結果の根拠が効いているかは、レスポンスの steps[].resultCount（0 より大きいか）と、生成側が返す sources_used などのフラグで判断できます。

{
  "steps": [
    { "id": "ctx", "type": "retrieve", "source": "repo", "query": "{input.question}", "filePath": "apps/api/src/modules/auth", "limit": 5 },
    { "id": "gen", "type": "generate", "prompt": "次のコードを根拠に回答。根拠が無ければその旨を明記。\n\n{steps.ctx.output}\n\n質問: {input.question}" }
  ],
  "inputs": { "question": "認証はどこで検証している？" },
  "mode": "sync"
}

• filePath（repo ソース時、任意）で検索範囲を絞り込めます。
• 索引が空のうちは resultCount: 0 になります。その場合はまず索引投入を完了させてください。

3.5 パイプラインの設計と登録

パイプラインの与え方は 2 通りあります。

A. インライン定義（steps）— 登録不要ですぐ試せる

リクエストの steps に直接ステップ配列を渡します。プロトタイピングや 1 回限りの実行に最適です（RAG を使わず generate だけなら索引も不要）。

{
  "steps": [
    { "id": "gen", "type": "generate", "prompt": "{input.text} を 3 行で要約" }
  ],
  "inputs": { "text": "..." },
  "mode": "sync"
}

B. 登録済みパイプライン（pipeline）— 再利用・チーム共有向け

定義を保存し、"pipeline": "<templateSlug>/<pipelineId>" で呼び出します。プロンプトやステップ構成を利用側コードから分離でき、更新が全呼び出しに即反映されます。

代表的な設計パターン

設計のヒント

• 変数展開（{input.*} {previousOutput} {context.<id>} {steps.<id>.output}）で前段の結果を後段プロンプトへ渡します。
• JSON 出力が欲しい生成ステップでは options.responseFormat を指定します（指定しない限り自由文で返り、json 未指定の JSON 強制による 400 を避けられます）。
• options.maxCostUsd と options.maxSteps で暴走を防ぎ、options.preferLocal でコスト/機密性に応じてローカル LLM を優先できます。

4. エラー・レート制限・コスト

• エラー形式: 4xx/5xx は JSON { error, message, traceId } を返す。ガードレールブロックは 422 { blocked: true, ... }、サーキット OPEN は 503。
• traceId: 全応答に付与。問い合わせ時に添付すると追跡が容易。
• レート制限: /auth/login 5/分、/llm/* 60/分、/orchestrate 30/分（いずれもテナント単位）。超過時は 429。
• コスト: 各応答の costUsd で実コストを確認可能（GET /llm/models の料金表に基づく）。

5. クイックスタート（cURL）

# 1) ログインしてトークンを取得
TOKEN=$(curl -s https://api.flauro-dev.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"********"}' | jq -r .access_token)

# 2) LLM を呼び出す
curl -s https://api.flauro-dev.com/api/v1/llm/call \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"こんにちは"}]}'

# 3) RAG つきオーケストレーション実行
curl -s https://api.flauro-dev.com/api/v1/orchestrate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"pipeline":"software_dev/pr_review","inputs":{"diff":"..."},"mode":"sync","options":{"model":"gpt-5.6-sol","preferLocal":false}}'