API — Ncost の事実を、自分の道具から使う

画面で確認できるコスト・根拠・結果を、画面の中に閉じ込めません。Ncost の公開 API は追加機能ではなく、製品の境界です。

Ncost は迷わず使える標準画面を提供します。そのうえで、組織固有の BI、通知、AI、レポート、承認フローは、公開後の API を使って既存の道具に残せる構想です。

API から取得できるもの 構想

データ	含まれるもの
Cost	日次・月次の実測コスト、provider、account、service、SKU、resource
Resource	リソース識別子、構成、観測時刻、取得状態
Finding	ルール、対象、推奨アクション、推定額、状態
Evidence	判定に使った facts、missing facts、危険条件
Coverage	取得できた範囲、欠測、権限不足、未検証
Rule	公開された判定条件、必要なデータ、version
Verified Result	観測した変更、一致度、比較 scope・期間、想定額、実測額、符号付き cost delta。検証不能は Coverage に保留理由を残す

これらは画面上の派生表示ではなく、APIでも同じID・同じ意味を持つ基本データです。「画面では見えるが取り出せない」状態を作りません。

画面とガイドでは対応する日本語を使います。名前の対応は用語 — 画面の言葉と API の名前を参照してください。

小さな API に保つ

OpenAPI と Bearer API キーを提供し、読み取りエンドポイントは上記の基本データとエクスポートに絞ります。Ncost 内の設定変更として必要な書き込みは、当面 write:tags による Virtual Tag の操作だけです。

次のための専用 API は作りません。

• JiraやLinearを再現するタスク・承認・コメント
• AIの推論過程やプロンプト管理
• Unit Economics、ROI、売上・利益配賦
• 任意SQL、任意JavaScript、顧客コード実行
• 汎用BIのダッシュボード定義

これらは Cost・Finding・Verified Result を取得し、利用者側で組み合わせられます。

キーの扱い

• キー全文は発行時に一度だけ表示し、以後は再表示しません
• キーは組織単位で発行し、readとwrite:tagsを分けます
• 一覧からいつでも失効でき、紛失時は失効して再発行します
• API 経由のタグ変更には、人間かエージェントかと producer を記録します

互換性方針

初期の API は、明瞭さを保つため破壊的変更を許容し、変更時に告知します。連携側は /v1/openapi.json の最新版を取得してから呼び出す設計を推奨します。

安定して利用される基本データとエンドポイントが固まった段階で、versionごとの互換性期間を定めます。未確定の互換性を先に約束するために、分かりにくいフィールドを残し続けることはしません。

機械可読ドキュメント

人向けHTMLに加えて、次を提供する計画です。

• サイト全体の索引を示す llms.txt
• ガイドとルールの Markdown 表現
• OpenAPI と JSON Schema
• ページの提供状態・最終更新・対応version

ルール・API・スキーマのリファレンスは、可能な範囲で実装から生成します。手書きの説明と実際の出力が別々に古くなることを防ぐためです。

エクスポート

API を継続して呼び続けなくても、Cost・Finding・Verified Result を CSV または JSON で取り出せるようにします。Ncost を使わなくなったあとも、これまで確認した結果を読める形式で保持できます。

AI による対話画面は必須にしない

AI チャットを Ncost の必須画面にはしません。公開後は、AI エージェントも OpenAPI と機械可読なガイドを読み、他の API 利用者と同じ根拠へアクセスできる構想です。

コード文脈の確認や独自エージェントとの接続は、Use your own toolsを参照してください。