Build Versioned Cost Manifests for AI API Releases

AI API cost reviews often fail in a quiet way.

The application team can point to the model ID. The platform team can point to the gateway route. Finance can point to a workbook. Security can point to a redaction rule. Procurement can point to a dated rate card. None of those artifacts are wrong, but they are often disconnected.

That disconnect matters when a Tier 1 or Tier 2 team moves from a prototype into a release train. The route that passed a demo last week may still answer requests today, while the pricing snapshot, cache assumption, route group, or receipt contract has changed.

A versioned cost manifest gives the release one small object to review.

It is not a billing system. It is not a marketing page. It is not a private log dump. It is a release artifact that says:

This AI API route was reviewed against these dated sources, with these assumptions, and these receipt fields must exist after the workload runs.

I will use AIWave as the concrete example because it exposes a public pricing snapshot at https://aiwave.live/api/v1/pricing and a live route table at https://aiwave.live/api/pricing. The pattern works for any OpenAI-compatible gateway or internal model platform.

As of September 18, 2026, the public AIWave pricing snapshot returned 56 model rows, checked=2026-09-10, updated_at=2026-09-18, currency USD, unit per_1m_text_tokens, and pricing version 83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5. The live route table returned 68 route rows, success=true, pricing version a42d372ccf0b5dd13ecf71203521f9d2, and group ratios default=1 and vip=0.9.

Those facts are not evergreen copy. Put the dates and versions into the manifest.

Why a manifest beats a spreadsheet note

Spreadsheets are useful for exploration. They are weak as release evidence.

A workbook can estimate expected spend, but it often loses the exact source version that fed the calculation. A release note can mention the model ID, but not the cache row or route group. A support ticket can hold a request receipt, but not the policy that made the route acceptable.

A manifest ties those pieces together without exposing private data.

At minimum, it should record:

Field	Why it exists
manifest_id	Stable handle for the release review
checked_at	When the evidence was collected
model_id	Exact ID used by the client or route
client_shape	API family, such as OpenAI-compatible chat completions
pricing_snapshot	URL, checked date, updated date, and version
route_table	URL, route count, group ratios, and version
rate_basis	Input, cache-hit input, and output rates used for planning
cache_assumption	Whether the release assumes cache hit behavior
output_cap	Maximum planned output for this path
retry_policy	Retry count and timeout budget
receipt_contract	Redacted fields expected after each run
unknowns	Missing evidence that reviewers must not infer

The unknowns field is not optional. It is where the manifest prevents optimism from becoming architecture.

A small manifest schema

Start with a boring JSON object.

{
  "manifest_id": "support-agent-route-2026-09-18",
  "checked_at": "2026-09-18T13:20:00Z",
  "client_shape": "openai_chat_completions",
  "model_id": "deepseek-flash",
  "pricing_snapshot": {
    "url": "https://aiwave.live/api/v1/pricing",
    "checked": "2026-09-10",
    "updated_at": "2026-09-18",
    "pricing_version": "83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5"
  },
  "route_table": {
    "url": "https://aiwave.live/api/pricing",
    "pricing_version": "a42d372ccf0b5dd13ecf71203521f9d2",
    "group_ratio": {
      "default": 1,
      "vip": 0.9
    }
  },
  "rate_basis": {
    "currency": "USD",
    "unit": "per_1m_text_tokens",
    "input": 0.7,
    "cache_hit_input": 0.0233,
    "output": 2.1,
    "effective_date": "2026-09-10"
  },
  "release_limits": {
    "max_output_tokens": 900,
    "max_retries": 1,
    "timeout_ms": 45000
  },
  "receipt_contract": [
    "request_id",
    "model_id",
    "prompt_tokens",
    "completion_tokens",
    "cache_status",
    "charged_amount"
  ],
  "unknowns": [
    "final invoice depends on selected account or key group",
    "cache behavior must be confirmed from request receipts"
  ]
}

This is intentionally not a prompt transcript. It does not contain an API key, request body, user identifier, customer name, or response text. A reviewer can understand the release economics without seeing private workload data.

Diff the manifest, not just the code

When the route changes, review the manifest diff beside the pull request.

For example, a code diff from deepseek-flash to glm-5.1 is easy to miss if it is hidden behind an environment variable. A manifest diff makes the change obvious:

- "model_id": "deepseek-flash"
+ "model_id": "glm-5.1"

- "input": 0.7
- "cache_hit_input": 0.0233
- "output": 2.1
+ "input": 2.1
+ "cache_hit_input": 0.680001
+ "output": 6.5999997

- "effective_date": "2026-09-10"
+ "effective_date": "2026-08-27"

That diff does not say one route is better. It says the release has a materially different cost profile and should be reviewed as such.

This is the right place to be precise. Avoid vague notes like "pricing changed" or "model upgraded". Say which row changed, which version was checked, and which assumption must be revalidated.

Treat cache as evidence, not hope

Many teams include cache-hit rows in forecasts because the number is attractive. The manifest should make a stricter distinction:

• rate_basis.cache_hit_input is the listed planning rate.
• cache_assumption is the workload belief.
• receipt_contract.cache_status is the runtime proof.

If the release cannot produce a receipt field that distinguishes cache behavior, do not let the forecast depend on it. The manifest can still list the cache-hit row, but the verdict should say that cache savings are not release evidence yet.

Example:

{
  "cache_assumption": {
    "used_in_forecast": false,
    "reason": "receipt validation has not yet proved cache status for this path"
  },
  "review_verdict": "ship_without_cache_savings_claim"
}

That sentence is dull, which is exactly the point. It keeps a launch from borrowing certainty from a pricing table.

Add a pre-release gate

A simple gate can run in CI or as a release checklist:

from __future__ import annotations

import json
import urllib.request


def load_json(url: str) -> dict:
    with urllib.request.urlopen(url, timeout=20) as response:
        return json.loads(response.read().decode("utf-8"))


manifest = json.load(open("cost-manifest.json", encoding="utf-8"))
snapshot = load_json(manifest["pricing_snapshot"]["url"])
routes = load_json(manifest["route_table"]["url"])

assert snapshot["pricing_version"] == manifest["pricing_snapshot"]["pricing_version"]
assert snapshot["updated_at"] == manifest["pricing_snapshot"]["updated_at"]
assert routes["pricing_version"] == manifest["route_table"]["pricing_version"]

row = next(
    item for item in snapshot["models"]
    if item["id"] == manifest["model_id"]
)

assert row["input_usd_per_1m_tokens"] == manifest["rate_basis"]["input"]
assert row["output_usd_per_1m_tokens"] == manifest["rate_basis"]["output"]
assert "charged_amount" in manifest["receipt_contract"]
assert "API_KEY" not in json.dumps(manifest)

In production, replace the assert statements with structured failures and an audit file. The gate should fail closed when a version moves, a row disappears, or the receipt contract no longer matches the route.

Keep the public claim narrower than the private proof

A release manifest can support internal decisions, but it should not automatically become public copy.

Safe public language:

This route was planned against a dated public pricing snapshot and a live route table checked on September 18, 2026.

Risky public language:

This route will always reduce cost.

The first statement names evidence. The second predicts an outcome without knowing workload shape, cache behavior, retries, output length, account group, and final receipt.

For AI API gateways, trust usually comes from narrower claims with better evidence. A versioned cost manifest is one way to keep the release honest: it lets engineering move quickly while giving finance, security, and procurement something concrete to review.

The result is not a heavier process. It is a smaller surface for argument.

Before the route ships, everyone can answer the same question:

Which dated pricing row, route version, group rule, cache assumption, and receipt contract did we approve?