# ⚠ このファイルは生成物。手で編集しない。
# 正本 = packages/backend/src/openapiSpec.ts(/openapi.json の配信元)。
# 再生成 = node scripts/gen-openapi-yaml.mjs(CI の check-openapi-sync が drift を落とす)。
# 公開先 = https://ingest.argosvix.com/openapi.json / https://argosvix.com/openapi.yaml
openapi: 3.1.0
info:
  title: Argosvix Ingest & Query API
  version: 1.0.0
  description: AI エージェント可観測性の公開 REST API。すべて Bearer API キー(`argk_...`)認証。プロジェクトスコープは `X-Project-Id` ヘッダで任意指定。
  contact:
    name: Argosvix
    url: https://argosvix.com
servers:
  - url: https://ingest.argosvix.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: ingest
    description: LLM 呼び出しレコードの取り込み
  - name: otlp
    description: OpenTelemetry トレース取り込み
  - name: query
    description: 集計・検索・エクスポート
  - name: account
    description: アカウント / API キー
  - name: eval
    description: 評価基準・データセット・評価実行・CI 回帰ゲート
  - name: prompts
    description: プロンプトレジストリ・バージョン・デプロイ/ロールバック
  - name: alerts
    description: アラート定義・サイレンス・確認・イベント
  - name: annotations
    description: 呼び出しへの注釈 / 品質ラベル
  - name: views
    description: 保存済みクエリビュー
  - name: safety
    description: 安全性アセスメント
  - name: guardian
    description: アカウント健全性スコア
  - name: webhooks
    description: 外向きイベント webhook
  - name: gate
    description: 運用ゲート(予算 / ポリシー / 承認)
  - name: proposals
    description: AI 提案の参照
  - name: projects
    description: プロジェクト管理
  - name: audit
    description: 監査ログ
  - name: health
    description: ヘルスチェック
  - name: public-data
    description: 公開データ(認証不要。Argosvix 自身の agent pipeline が毎日生成)
paths:
  /v1/ingest:
    post:
      tags:
        - ingest
      summary: LLM 呼び出しレコードを投入
      description: 最大 100 件/リクエスト。`id` 必須(冪等キー)。月次レコード数がプラン上限を超えると 429(`Retry-After` に翌月 1 日 00:00 UTC までの秒数)。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestRequest'
      responses:
        '200':
          description: 受理(冪等で一部スキップされた件数を含む)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited / quota exceeded. `Retry-After` ヘッダに再試行までの秒数。
          headers:
            Retry-After:
              schema:
                type: integer
              description: 再試行可能になるまでの秒数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/traces:
    post:
      tags:
        - otlp
      summary: OTLP/HTTP トレース取り込み(http/json + http/protobuf 両対応)
      description: >-
        OpenTelemetry GenAI スパンを取り込む。エクスポータのプロトコルは **http/json**(`application/json`)と
        **http/protobuf**(`application/x-protobuf`)の両方に対応。`gen_ai.*` 属性のないスパンは typed observation として保存。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: OTLP ExportTraceServiceRequest(JSON エンコード)
          application/x-protobuf:
            schema:
              type: string
              format: binary
              description: OTLP ExportTraceServiceRequest(protobuf エンコード)
      responses:
        '200':
          description: 取り込み結果。OTel エクスポータの再送回避のため業務拒否も 200 + partialSuccess。
        '400':
          description: JSON / protobuf いずれかの parse 失敗(リトライ非対象)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: body が上限(1 MiB)超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/calls:
    post:
      tags:
        - query
      summary: 呼び出しレコードの検索
      description: フィルタ(期間 / provider / model / タグ / エラー)+ ソート + ページング。
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryCallsRequest'
      responses:
        '200':
          description: レコード配列
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallRecord'
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/calls/{id}:
    get:
      tags:
        - query
      summary: 単一呼び出しレコード
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: レコード(`call` でラップ)
          content:
            application/json:
              schema:
                type: object
                properties:
                  call:
                    $ref: '#/components/schemas/CallRecord'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/trace/{id}:
    get:
      tags:
        - query
      summary: トレース(同一 trace_id のスパン群)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: スパン群
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/session/{id}:
    get:
      tags:
        - query
      summary: セッション(同一 session_id の呼び出し群)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 呼び出し群
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/aggregate:
    post:
      tags:
        - query
      summary: 集計キューブ
      description: >-
        groupBy(provider/model/day/hour/minute/tag/error)×
        metric(cost/latency/tokens/input_tokens/output_tokens/cached_tokens/cache_savings/count/error_rate)。
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregateRequest'
      responses:
        '200':
          description: groups + total
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/percentiles:
    post:
      tags:
        - query
      summary: レイテンシ / コストのパーセンタイル
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startTime:
                  type: string
                  format: date-time
                endTime:
                  type: string
                  format: date-time
                provider:
                  type: string
                model:
                  type: string
                metric:
                  type: string
                  enum:
                    - latency
                    - cost
                groupBy:
                  type: string
                  enum:
                    - day
                    - hour
                    - minute
                  description: 指定すると bucket series(byDay)を返す。省略 = 全期間 1 数値。
                tzOffsetMinutes:
                  type: integer
                  minimum: -840
                  maximum: 840
                  description: groupBy=day 限定。aggregate と同じローカル日束ね(固定オフセット)。
      responses:
        '200':
          description: p50/p90/p95/p99 等
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/distribution:
    post:
      tags:
        - query
      summary: ヒストグラム分布(レイテンシ / コスト)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: bucket 配列
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/query/export:
    post:
      tags:
        - query
      summary: 呼び出しのエクスポート(JSON / CSV)
      description: >-
        プラン別上限(Free 1,000 / Pro 50,000 件)まで返す。フィルタ仕様は /v1/query/calls と同じ。`?format=csv` または `Accept: text/csv` で
        CSV(UTF-8 BOM 付き、`text/csv`)。既定は JSON。
      security:
        - bearerAuth: []
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - json
              - csv
          description: 出力形式(既定 json)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryCallsRequest'
      responses:
        '200':
          description: JSON(records)または CSV テキスト
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallRecord'
            text/csv:
              schema:
                type: string
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/account:
    get:
      tags:
        - account
      summary: アカウントの識別 / プラン / クォータのスナップショット
      security:
        - bearerAuth: []
      responses:
        '200':
          description: アカウント情報
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-criteria:
    get:
      tags:
        - eval
      summary: 評価基準の一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 評価基準の配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - eval
      summary: 評価基準の作成(Pro+)
      description: >-
        `type`(既定 llm_judge / exact_match / contains / regex / json_schema / json_path)と`scoreType`(numeric / boolean /
        categorical)を指定。決定的評価器は LLM・予算不要。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvalCriterionInput'
      responses:
        '200':
          description: 更新後の評価基準一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-criteria/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - eval
      summary: 評価基準の取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 評価基準
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - eval
      summary: 評価基準の更新(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvalCriterionInput'
      responses:
        '200':
          description: 更新後の一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - eval
      summary: 評価基準の削除(Pro+)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 更新後の一覧
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-criteria/presets:
    get:
      tags:
        - eval
      summary: 組込み評価器プリセット一覧(RAG / 品質 / 安全)
      description: faithfulness / answer_relevance / conciseness 等の llm_judge 基準テンプレ。POST /v1/eval-criteria でそのまま作成可能。
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ presets: [{ key, category, name, rubric, scaleMin, scaleMax, type, scoreType, descriptionJa }] }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-criteria/propose:
    post:
      tags:
        - eval
      summary: ユースケースから評価基準を LLM 提案(Pro+ / 要 AI 同意)
      description: '`useCaseHint` 必須。LLM 予算から少額消費。レート制限 30 req/60s。'
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - useCaseHint
              properties:
                useCaseHint:
                  type: string
                  minLength: 1
                  maxLength: 500
                sampleCallIds:
                  type: array
                  items:
                    type: string
                  maxItems: 5
                maxCriteria:
                  type: integer
                  minimum: 1
                  maximum: 10
      responses:
        '200':
          description: 提案された基準
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited / quota exceeded. `Retry-After` ヘッダに再試行までの秒数。
          headers:
            Retry-After:
              schema:
                type: integer
              description: 再試行可能になるまでの秒数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-datasets:
    get:
      tags:
        - eval
      summary: 評価データセットの一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: データセット配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - eval
      summary: 評価データセットの作成(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                description:
                  type: string
                  nullable: true
                  maxLength: 500
                promptRegistryId:
                  type: integer
                  nullable: true
                frozen:
                  type: boolean
                items:
                  type: array
                  maxItems: 20
                  items:
                    type: object
                    required:
                      - inputText
                    properties:
                      inputText:
                        type: string
                        minLength: 1
                        maxLength: 4000
                      expectedOutput:
                        type: string
                        nullable: true
                        maxLength: 4000
      responses:
        '200':
          description: 作成されたデータセット
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-datasets/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - eval
      summary: データセットの取得(項目込み)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: データセット
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - eval
      summary: データセットの更新(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 更新後
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - eval
      summary: データセットの削除(Pro+)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ ok: true }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-datasets/{id}/run:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    post:
      tags:
        - eval
      summary: データセット評価の実行(Pro+)
      description: レート制限 10 回/5 分。`idempotencyKey` で 60 分の重複排除。
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotencyKey:
                  type: string
                  maxLength: 64
      responses:
        '200':
          description: '{ runId, deduplicated }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited / quota exceeded. `Retry-After` ヘッダに再試行までの秒数。
          headers:
            Retry-After:
              schema:
                type: integer
              description: 再試行可能になるまでの秒数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-runs:
    get:
      tags:
        - eval
      summary: 評価実行の一覧
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: 実行の配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - eval
      summary: 評価実行の作成と起動(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                recentCount:
                  type: integer
                label:
                  type: string
                promptRegistryId:
                  type: integer
                idempotencyKey:
                  type: string
                  maxLength: 64
      responses:
        '200':
          description: '{ summary, deduped }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-runs/judge-agreement:
    get:
      tags:
        - eval
      summary: ジャッジ vs 人手の一致度(人手スコアと judge スコアの両方がある call の meta-eval)
      description: >-
        criterion scale で正規化した judge スコアと人手 quality_score を比較。{ pairedCalls, meanHuman, meanJudge, meanAbsDiff,
        agreementPctWithin1, pairs[] }。
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 一致度サマリ + 直近の対
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-runs/judge-trust:
    get:
      tags:
        - eval
      summary: ジャッジ信頼度の成分(変異プローブの識別/安定 + 人手一致)
      description: >-
        週次の自動プローブ(機械的改悪の識別テスト)の直近 30 日集計と人手一致を成分別に返す。{ probe: { probes, detectedPct, stablePct, invertedCount, byKind },
        human: { pairedCalls, agreementPctWithin1, meanAbsDiff }, trustEstablished }。
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 信頼度成分サマリ
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-runs/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - eval
      summary: 評価実行の詳細(スコア込み)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ run, scores }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-runs/compare:
    get:
      tags:
        - eval
      summary: 2 つの実行を比較
      security:
        - bearerAuth: []
      parameters:
        - name: baseline
          in: query
          required: true
          schema:
            type: integer
        - name: candidate
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 基準差分 + verdict
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/eval-runs/gate:
    get:
      tags:
        - eval
      summary: CI 回帰ゲート(候補 run を基準と比較し合否判定)
      description: >-
        閾値超過の回帰があれば `pass:false` + `violations`。`baselineName` を渡すと同名で候補より前の最新 completed run を自動採用。初回は
        `allowMissingBaseline=true` で許可。
      security:
        - bearerAuth: []
      parameters:
        - name: candidate
          in: query
          required: true
          schema:
            type: integer
        - name: baseline
          in: query
          schema:
            type: integer
        - name: baselineName
          in: query
          schema:
            type: string
        - name: maxMeanDrop
          in: query
          schema:
            type: number
        - name: maxNewFailures
          in: query
          schema:
            type: integer
        - name: maxCriterionDrop
          in: query
          schema:
            type: number
        - name: allowMissingBaseline
          in: query
          schema:
            type: boolean
        - name: requireSignificance
          in: query
          schema:
            type: boolean
          description: true で criterion 下落を統計的に有意(p<0.05)な場合のみ違反に数える
      responses:
        '200':
          description: '{ pass, verdict, violations, baselineResolved, criterionDeltas[].pValue/significant, ... }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts:
    get:
      tags:
        - prompts
      summary: プロンプトの一覧
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: label
          in: query
          schema:
            type: string
      responses:
        '200':
          description: プロンプト配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - prompts
      summary: プロンプトの作成(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - version
                - template
              properties:
                name:
                  type: string
                version:
                  type: string
                template:
                  type: string
                  description: 最大 50000 バイト
                variables:
                  type: object
                  nullable: true
                labels:
                  type: array
                  items:
                    type: string
                  maxItems: 8
                description:
                  type: string
                  nullable: true
                  maxLength: 500
      responses:
        '200':
          description: '{ prompt, warnings }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts/resolve:
    get:
      tags:
        - prompts
      summary: デプロイ済みプロンプトの解決
      description: '`name` + `label`(環境)で現在デプロイされているバージョンを返す。'
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
        - name: label
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: '{ prompt, label }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts/deployments:
    get:
      tags:
        - prompts
      summary: デプロイの一覧
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: label
          in: query
          schema:
            type: string
      responses:
        '200':
          description: デプロイ配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts/deployments/rollback:
    post:
      tags:
        - prompts
      summary: デプロイのロールバック(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - label
              properties:
                name:
                  type: string
                label:
                  type: string
      responses:
        '200':
          description: 更新後のデプロイ一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - prompts
      summary: プロンプトの取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ prompt }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - prompts
      summary: プロンプトの更新(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: '{ prompt, warnings }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - prompts
      summary: プロンプトの削除(Pro+)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ deletedId }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts/{id}/rename:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    post:
      tags:
        - prompts
      summary: プロンプトの改名(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - version
              properties:
                name:
                  type: string
                version:
                  type: string
      responses:
        '200':
          description: '{ prompt }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/prompts/{id}/deploy:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    post:
      tags:
        - prompts
      summary: プロンプトのデプロイ(Pro+)
      description: 指定バージョンを `label`(環境)に割当。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
              properties:
                label:
                  type: string
      responses:
        '200':
          description: デプロイ一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts:
    get:
      tags:
        - alerts
      summary: アラートの一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: アラート配列(秘匿値はマスク)
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - alerts
      summary: アラートの作成
      description: Free は email のみ 3 件まで、Pro+ は全チャネル無制限。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertInput'
      responses:
        '200':
          description: '{ id }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts/events:
    get:
      tags:
        - alerts
      summary: アラートイベントの一覧(通知センター)
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: alertId
          in: query
          schema:
            type: string
        - name: beforeTriggeredAt
          in: query
          schema:
            type: string
            format: date-time
        - name: beforeId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: イベント配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts/templates:
    get:
      tags:
        - alerts
      summary: アラートテンプレートの一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: テンプレート配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts/test-webhook:
    post:
      tags:
        - alerts
      summary: webhook 配信のテスト(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                secret:
                  type: string
                alertName:
                  type: string
      responses:
        '200':
          description: '{ ok, delivered, message }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - alerts
      summary: アラートの詳細(直近イベント込み)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ alert, events }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - alerts
      summary: アラートの更新
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: '{ updated: true }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - alerts
      summary: アラートの削除
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ deleted: true }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts/{id}/silence:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - alerts
      summary: アラートのサイレンス
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                until:
                  type: string
                  format: date-time
                  nullable: true
      responses:
        '200':
          description: '{ silencedUntil }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - alerts
      summary: サイレンス解除
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ silencedUntil: null }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/alerts/events/{eventId}/acknowledge:
    parameters:
      - name: eventId
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - alerts
      summary: アラートイベントの確認
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
      responses:
        '200':
          description: '{ id, acknowledgedAt, acknowledgedBy, alreadyAcknowledged }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/annotations:
    get:
      tags:
        - annotations
      summary: 注釈の一覧(callId または label でフィルタ)
      security:
        - bearerAuth: []
      parameters:
        - name: callId
          in: query
          schema:
            type: string
        - name: label
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: 注釈配列
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - annotations
      summary: 注釈の作成
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - callId
              properties:
                callId:
                  type: string
                annotationText:
                  type: string
                  nullable: true
                  maxLength: 2000
                label:
                  type: string
                  nullable: true
                  maxLength: 50
                qualityScore:
                  type: integer
                  minimum: 1
                  maximum: 5
                  nullable: true
      responses:
        '200':
          description: '{ annotation }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/annotations/review-queue:
    get:
      tags:
        - annotations
      summary: 人手レビュー待ち行列(未採点の実呼び出し + カバレッジ)
      description: 窓内で人手の quality_score がまだ無い実呼び出しをエラー優先で返す。eval 実行記録は除外。coverage に採点済み/母数/カバレッジ%。
      security:
        - bearerAuth: []
      parameters:
        - name: windowDays
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 90
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: '{ items[], coverage{total,reviewed,pending,coveragePct} }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/annotations/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - annotations
      summary: 注釈の取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ annotation }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - annotations
      summary: 注釈の更新
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: '{ annotation }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - annotations
      summary: 注釈の削除
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ deletedId }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/saved-views:
    get:
      tags:
        - views
      summary: 保存ビューの一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: ビュー配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - views
      summary: 保存ビューの作成 / 更新(最大 20 件)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - filter
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 50
                filter:
                  type: object
      responses:
        '200':
          description: 更新後のビュー一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/saved-views/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    delete:
      tags:
        - views
      summary: 保存ビューの削除
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 更新後の一覧
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/safety-assessments:
    get:
      tags:
        - safety
      summary: 安全性アセスメントの一覧
      security:
        - bearerAuth: []
      parameters:
        - name: call_id
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: アセスメント配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/safety-assessments/scan-batch:
    post:
      tags:
        - safety
      summary: オンデマンド安全性スキャン(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                maxRecords:
                  type: integer
                  minimum: 1
                  maximum: 100
      responses:
        '200':
          description: '{ scanned, assessed, flagged, failures, skipped }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/safety-assessments/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - safety
      summary: アセスメントの取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ assessment }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/guardian/health:
    get:
      tags:
        - guardian
      summary: 'アカウント健全性スコア(計測済みの柱の単純平均: 品質 / エラー / 安全 / 指摘対応)'
      security:
        - bearerAuth: []
      parameters:
        - name: window
          in: query
          schema:
            type: string
            enum:
              - 24h
              - 7d
          description: 採点の窓(既定 7d)
      responses:
        '200':
          description: >-
            { health: { score, band, verdict, subscores: { quality, reliability, safety, findings }, openFindings,
            capabilities, ... } }
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/webhooks:
    get:
      tags:
        - webhooks
      summary: 外向き webhook の一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: webhook 配列(秘密はマスク)
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - webhooks
      summary: 外向き webhook の作成(Pro+ = 10 本・全イベント、Free = approval.requested のみ 1 本)
      description: >-
        対応イベント: approval.requested / proposal.executed / proposal.reversed。`eventTypes` 空配列 = 全イベント(Pro+ のみ)。`format`
        省略時は URL から自動判定(hooks.slack.com = slack、それ以外 = json)。slack は人間向けの {text} 文面、json は機械向けの envelope を配信する。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: https のみ(SSRF 検証)
                secret:
                  type: string
                  nullable: true
                  minLength: 12
                  maxLength: 512
                enabled:
                  type: boolean
                eventTypes:
                  type: array
                  items:
                    type: string
                description:
                  type: string
                  nullable: true
                  maxLength: 200
                format:
                  type: string
                  enum:
                    - json
                    - slack
                  description: 省略 = URL から自動判定
      responses:
        '200':
          description: 更新後の webhook 一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/webhooks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    patch:
      tags:
        - webhooks
      summary: webhook の更新(url/secret/enabled/eventTypes/description/format。Free は approval.requested のみ購読可)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 更新後の一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - webhooks
      summary: webhook の削除
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 更新後の一覧
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/webhooks/{id}/test:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - webhooks
      summary: webhook へ test.ping を試送(5 送/分)
      description: 登録済み webhook へ署名付きのテストイベントを即時配信し、配信の成否を返す。結果は一覧の直近配信状態にも反映される。
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ ok, delivered, statusCode, message }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/calls/{id}/plaintext:
    get:
      tags:
        - query
      summary: 保存済み平文(プロンプト / 応答)のレコード単位復号(平文保管オプトイン時のみ)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: '{ promptBody, completionBody, toolCalls, contentKid, decryptedAt }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/calls/bulk-delete:
    post:
      tags:
        - query
      summary: 呼び出しレコードの一括削除
      description: 最大 100 件。`dryRun` で件数のみ確認。`approvalId` で事前承認を消費。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - callIds
              properties:
                callIds:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                dryRun:
                  type: boolean
                approvalId:
                  type: string
      responses:
        '200':
          description: '{ deleted, requested } または dryRun 集計'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/guardian/health/trend:
    get:
      tags:
        - guardian
      summary: 健全性スコアの推移(24h = 生の記録から、7d/30d/90d = 日次スナップショット)
      security:
        - bearerAuth: []
      parameters:
        - name: range
          in: query
          schema:
            type: string
            enum:
              - 24h
              - 7d
              - 30d
              - 90d
          description: 既定 7d
      responses:
        '200':
          description: >-
            { trend: { range, points: [{ at, score, quality, reliability, safety, findings }], complete, since, source }
            }
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/account/llm-feature-budget:
    get:
      tags:
        - account
      summary: Argosvix 内部 AI 機能(safety / PII 監査 / eval)の月次 LLM 予算と消費
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ budgetUsd, spentUsd, remainingUsd, periodStart, defaultBudgetUsd, minBudgetUsd, maxBudgetUsd }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/account/llm-feature-budget/snapshots:
    get:
      tags:
        - account
      summary: 内部 AI 機能予算の月次スナップショット履歴
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ snapshots: [{ yearMonth, budgetUsd, spentUsd, snapshotAt }] }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/health:
    get:
      tags:
        - health
      summary: 稼働確認(認証不要)
      security: []
      responses:
        '200':
          description: '{ status: "ok", service, version, time, checks: { db: { ok, latencyMs } } }'
          content:
            application/json:
              schema:
                type: object
        '503':
          description: 'DB 不達(status: degraded)'
  /v1/synth-daily/latest:
    get:
      tags:
        - public-data
      summary: Synth Daily(日刊 AI ダイジェスト)の最新号(認証不要)
      security: []
      responses:
        '200':
          description: >-
            { issue: { date, scoop, items: [{ rank, name, desc, why, sourceUrl, metric, nameEn?, descEn?, whyEn? }],
            generation?, generatedAt } }
          content:
            application/json:
              schema:
                type: object
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/synth-daily:
    get:
      tags:
        - public-data
      summary: Synth Daily の号一覧(新しい順)/ date 指定で単一号(認証不要)
      security: []
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
          description: 指定するとその号だけを { issue } で返す
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 30
          description: 一覧の件数(既定 8)
      responses:
        '200':
          description: '{ issues: [...] } または { issue }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/synth-daily/dates:
    get:
      tags:
        - public-data
      summary: Synth Daily の全号日付一覧(認証不要)
      security: []
      responses:
        '200':
          description: '{ dates: ["YYYY-MM-DD", ...] }'
          content:
            application/json:
              schema:
                type: object
  /v1/synth-daily/rss:
    get:
      tags:
        - public-data
      summary: Synth Daily の RSS 2.0 フィード(認証不要)
      security: []
      parameters:
        - name: lang
          in: query
          schema:
            type: string
            enum:
              - ja
              - en
          description: 既定 ja
      responses:
        '200':
          description: application/rss+xml
  /v1/forecast:
    get:
      tags:
        - public-data
      summary: ビルド予報の現在盤面(active カード + 票 + 直近の動き、認証不要)
      security: []
      responses:
        '200':
          description: >-
            { cards: [{ id, proposedAt, proposedBy, card, ja?, hash }], votes: [{ model, card_id, reason, since }],
            recentEvents }
          content:
            application/json:
              schema:
                type: object
  /v1/forecast/ledger:
    get:
      tags:
        - public-data
      summary: ビルド予報の全台帳(撤回・判定済み込み、認証不要)
      security: []
      responses:
        '200':
          description: '{ cards, events }'
          content:
            application/json:
              schema:
                type: object
  /v1/forecast/archive:
    get:
      tags:
        - public-data
      summary: ビルド予報の日次アーカイブ一覧(スナップショットのある日付、認証不要)
      security: []
      responses:
        '200':
          description: '{ dates: ["YYYY-MM-DD"] }'
          content:
            application/json:
              schema:
                type: object
  /v1/forecast/archive/{date}:
    get:
      tags:
        - public-data
      summary: ビルド予報の指定日の盤面スナップショット(認証不要)
      security: []
      parameters:
        - name: date
          in: path
          required: true
          schema:
            type: string
          description: YYYY-MM-DD
      responses:
        '200':
          description: '{ date, cards, votes, recentEvents }'
          content:
            application/json:
              schema:
                type: object
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/growth:
    get:
      tags:
        - public-data
      summary: Growth Board(成長盤)の週次台帳(KPI・提案・投票・採用・結果、認証不要)
      security: []
      responses:
        '200':
          description: >-
            { weeks: [{ weekStart, kpi, adoptedProposalId, adoptedNote, result, status }], proposals: [{ id, weekStart,
            model, role, core, hash, ja?, disqualified, disqualifyReason, annotations }], votes: [{ weekStart, model,
            proposalId, reason, jaReason }] }
          content:
            application/json:
              schema:
                type: object
  /v1/readthrough/latest:
    get:
      tags:
        - public-data
      summary: Wisp readthrough(AI の OSS 読解記録)の最新公開号(認証不要)
      security: []
      responses:
        '200':
          description: >-
            { issue: { date, repo: { owner, name, url, language?, license?, stars? }, oneLiner, keyFiles, highlights,
            cautions, generation?, traceId?, generatedAt } }
          content:
            application/json:
              schema:
                type: object
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/readthrough:
    get:
      tags:
        - public-data
      summary: Wisp readthrough の単一号(date 指定)/ 省略で最新号(認証不要)
      security: []
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: '{ issue }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/readthrough/dates:
    get:
      tags:
        - public-data
      summary: Wisp readthrough の公開号日付一覧(認証不要)
      security: []
      responses:
        '200':
          description: '{ dates: ["YYYY-MM-DD", ...] }'
          content:
            application/json:
              schema:
                type: object
  /v1/providers/status:
    get:
      tags:
        - health
      summary: LLM プロバイダの稼働状況(キャッシュ)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: プロバイダ状態配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/audit-log:
    get:
      tags:
        - audit
      summary: 監査ログ(API キーは管理者扱い)
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
        - name: eventType
          in: query
          schema:
            type: string
        - name: targetKind
          in: query
          schema:
            type: string
        - name: actorUserId
          in: query
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: '{ events, nextCursor }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/config:
    get:
      tags:
        - gate
      summary: 予算 + ポリシーゲートをまとめて取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ budget, policy, ttlSeconds }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/budget:
    get:
      tags:
        - gate
      summary: 予算ゲートと当月消費
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ gates, spentUsdThisMonth, monthStart }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - gate
      summary: 予算ゲートの作成(Pro+)
      description: >-
        projectId 省略 = account 全体 gate。 proj_ 指定 = プロジェクト別 gate(account gate と AND)。 tagKey + tagValue 指定 = タグ別
        gate(両方必須・projectId とは排他)。
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - monthlyLimitUsd
              properties:
                monthlyLimitUsd:
                  type: number
                  minimum: 0.01
                enforceMode:
                  type: string
                  enum:
                    - fail_open
                    - fail_closed
                enabled:
                  type: boolean
                projectId:
                  type: string
                  description: proj_ 形式(省略=account 全体)
                tagKey:
                  type: string
                  description: タグ別 gate の key(tagValue と同時指定・projectId 排他)
                tagValue:
                  type: string
                  description: タグ別 gate の value(tagKey と同時指定)
      responses:
        '200':
          description: 更新後のゲート一覧
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/budget/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    patch:
      tags:
        - gate
      summary: 予算ゲートの更新(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                monthlyLimitUsd:
                  type: number
                enforceMode:
                  type: string
                  enum:
                    - fail_open
                    - fail_closed
                enabled:
                  type: boolean
      responses:
        '200':
          description: 更新後
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - gate
      summary: 予算ゲートの削除(Pro+)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ ok: true }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/policy:
    get:
      tags:
        - gate
      summary: ポリシーゲートの取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ policy }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - gate
      summary: ポリシーゲートの作成(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rules
              properties:
                rules:
                  type: object
      responses:
        '200':
          description: ポリシー
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/policy/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    patch:
      tags:
        - gate
      summary: ポリシーゲートの更新(Pro+)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 更新後
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - gate
      summary: ポリシーゲートの削除(Pro+)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ ok: true }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/approvals:
    get:
      tags:
        - gate
      summary: 承認の一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 承認配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - gate
      summary: 承認の作成
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                args:
                  type: object
                expiresInSeconds:
                  type: integer
      responses:
        '200':
          description: 作成された承認
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/approvals/counts:
    get:
      tags:
        - gate
      summary: 承認のステータス件数
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ pending, approved, rejected, expired }'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/gate/approvals/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - gate
      summary: 承認の取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 承認
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/proposals:
    get:
      tags:
        - proposals
      summary: 未処理の AI 提案の一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 提案配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/proposals/{id}/messages:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - proposals
      summary: 提案のスレッドメッセージ
      security:
        - bearerAuth: []
      responses:
        '200':
          description: メッセージ配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects:
    get:
      tags:
        - projects
      summary: プロジェクトの一覧
      security:
        - bearerAuth: []
      responses:
        '200':
          description: プロジェクト配列
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - projects
      summary: プロジェクトの作成(Free=1 / Pro=5 / Team=無制限)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - slug
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 64
                slug:
                  type: string
                  pattern: ^[a-z][a-z0-9-]{0,31}$
      responses:
        '201':
          description: 作成されたプロジェクト
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - projects
      summary: プロジェクトの取得
      security:
        - bearerAuth: []
      responses:
        '200':
          description: プロジェクト
          content:
            application/json:
              schema:
                type: object
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - projects
      summary: プロジェクトの更新
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 更新後
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - projects
      summary: プロジェクトのアーカイブ
      security:
        - bearerAuth: []
      responses:
        '200':
          description: '{ ok, archivedAt }'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /health:
    get:
      tags:
        - health
      summary: ヘルスチェック
      security: []
      responses:
        '200':
          description: OK
  /v1/health/cron:
    get:
      tags:
        - health
      summary: 定期処理(cron)の鮮度チェック。最終 tick が 45 分より古いと 503(外形監視用)
      security: []
      responses:
        '200':
          description: '{ status: ''ok'', lastTickAt, ageSeconds, staleAfterSeconds }'
          content:
            application/json:
              schema:
                type: object
        '503':
          description: cron が沈黙している(stale)
  /openapi.json:
    get:
      tags:
        - health
      summary: この OpenAPI 仕様
      security: []
      responses:
        '200':
          description: OpenAPI 3.1 ドキュメント
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API キー `argk_...` を `Authorization: Bearer <key>` で。'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    IngestRequest:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/IngestRecord'
    IngestRecord:
      type: object
      required:
        - id
        - provider
        - model
        - promptTokens
        - completionTokens
        - totalTokens
        - costUsd
        - latencyMs
        - timestamp
      properties:
        id:
          type: string
          description: 冪等キー(必須)
        provider:
          type: string
          enum:
            - openai
            - anthropic
            - gemini
            - mistral
            - xai
            - moonshot
            - deepseek
            - alibaba
            - meta
        model:
          type: string
        promptTokens:
          type: integer
        completionTokens:
          type: integer
        totalTokens:
          type: integer
        cachedReadTokens:
          type: integer
          description: プロンプトキャッシュ読取(任意)
        cachedWriteTokens:
          type: integer
          description: プロンプトキャッシュ書込(任意)
        costUsd:
          type: number
        cacheSavingsUsd:
          type: number
          description: キャッシュ節約額(任意)
        latencyMs:
          type: integer
        ttftMs:
          type: integer
          description: 初回トークンまでの時間 ms(streaming のみ、任意)
        reasoningTokens:
          type: integer
          description: 推論トークン(思考モデル、任意)
        audioTokens:
          type: integer
          description: 音声トークン(入力+出力合算、任意)
        timestamp:
          type: string
          format: date-time
        tags:
          type: object
          additionalProperties:
            type: string
        error:
          type: string
        traceId:
          type: string
        spanId:
          type: string
        parentSpanId:
          type: string
        sessionId:
          type: string
    IngestResponse:
      type: object
      properties:
        accepted:
          type: integer
        rejected:
          type: integer
        reasons:
          type: array
          items:
            type: string
    QueryCallsRequest:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        provider:
          type: string
          enum:
            - openai
            - anthropic
            - gemini
            - mistral
            - xai
            - moonshot
            - deepseek
            - alibaba
            - meta
        model:
          type: string
        errorOnly:
          type: boolean
        limit:
          type: integer
        cursor:
          type: string
        sortBy:
          type: string
          enum:
            - timestamp
            - provider
            - model
            - total_tokens
            - cost_usd
            - latency_ms
            - error
        sortOrder:
          type: string
          enum:
            - asc
            - desc
    AggregateRequest:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        groupBy:
          type: string
          enum:
            - provider
            - model
            - day
            - hour
            - minute
            - tag
            - error
        metric:
          type: string
          enum:
            - cost
            - latency
            - tokens
            - input_tokens
            - output_tokens
            - cached_tokens
            - cache_savings
            - reasoning_tokens
            - audio_tokens
            - ttft
            - count
            - error_rate
        tagKey:
          type: string
        tzOffsetMinutes:
          type: integer
          minimum: -840
          maximum: 840
          description: >-
            groupBy=day 限定。端末のタイムゾーンオフセット(分、東京 = +540)を渡すとローカル日で束ねる。省略 = UTC 日。固定オフセットのため、DST のある地域で切替をまたぐ期間は境界が最大 1
            時間ずれる。
    CallRecord:
      type: object
      properties:
        id:
          type: string
        provider:
          type: string
        model:
          type: string
        promptTokens:
          type: integer
        completionTokens:
          type: integer
        totalTokens:
          type: integer
        costUsd:
          type: number
        latencyMs:
          type: integer
        timestamp:
          type: string
          format: date-time
        tags:
          type: object
          additionalProperties:
            type: string
        error:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
        spanId:
          type: string
          nullable: true
        sessionId:
          type: string
          nullable: true
    EvalCriterionInput:
      type: object
      required:
        - name
        - rubric
        - scaleMin
        - scaleMax
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
        rubric:
          type: string
          minLength: 10
          maxLength: 2000
        scaleMin:
          type: integer
          minimum: 1
          maximum: 100
        scaleMax:
          type: integer
          minimum: 1
          maximum: 100
        type:
          type: string
          enum:
            - llm_judge
            - exact_match
            - contains
            - regex
            - json_schema
            - json_path
          description: 既定 llm_judge。決定的評価器は LLM・予算不要
        config:
          type: object
          nullable: true
          description: 決定的評価器の設定(categorical の categories など)
        scoreType:
          type: string
          enum:
            - numeric
            - boolean
            - categorical
          description: categorical は llm_judge のみ。既定 numeric
    AlertInput:
      type: object
      required:
        - name
        - alertType
        - channelKinds
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        alertType:
          type: string
          enum:
            - cost_threshold
            - error_rate
            - latency_degradation
            - monthly_budget
            - anomaly_cost
            - anomaly_latency
            - anomaly_error_rate
            - eval_score
            - guardian_findings
        thresholdValue:
          type: number
          minimum: 0
          description: guardian_findings 以外で必須(guardian_findings では無視)
        windowMinutes:
          type: integer
          minimum: 5
          maximum: 43200
          description: anomaly_* / guardian_findings では無視(60 固定)
        filterProvider:
          type: string
          nullable: true
        filterModel:
          type: string
          nullable: true
        channelKinds:
          type: array
          items:
            type: string
            enum:
              - email
              - slack
              - discord
              - teams
              - webhook
              - pagerduty
        channelTargets:
          type: object
          description: チャネル別の宛先 / 秘密(応答ではマスク)
        sleepMinutes:
          type: integer
          minimum: 5
          maximum: 604800
        enabled:
          type: boolean
        conditions:
          type: object
          nullable: true
        evalCriterionId:
          type: string
          description: eval_score 型で必須
        config:
          type: object
          nullable: true
          description: 'guardian_findings のカテゴリ絞り込み(例 {"categories": ["quality", "safety"]}。未指定 = 全カテゴリ)'