Changelog

v0.3.0 - 2026-04-27

CLI is now first-class in the docs

The l4 CLI gets a top-level /cli section: installation, authentication, output formats (--json, --jq, --template, --csv, --quiet, --web), per-command reference, and validated multi-step recipes — including a flagship pipeline that aggregates 100% savings recommendations across all pages with one CloudWatch summary row. Every recipe is checked by npm run validate:recipes against the live API.

The previous "Building a CLI" guide has been replaced by two integration guides that match real customer scenarios:

• Integrate the SDK into your CLI — embed the LevelFour SDK as a library inside an existing internal CLI (Python / TypeScript / Go)
• Integrate l4 into your CLI — shell out to the official l4 binary from scripts, Makefiles, and CI runners with no SDK dependency

CLI changes

• New 3-tab interactive TUI for l4 recommendations view (Recommendation / Comparison / Risk & Implementation), with code-block scroll navigation
• New interactive split-pane TUI for l4 costs breakdown
• l4 recommendations list rebuilt with KPI cards and live filters (--provider, --service, --account, --environment, --tag, --status, --search)
• Spinners are now suppressed when stdout is not a TTY — clean JSON for shell pipelines
• Brand color refresh

API changes

• Filter options are cross-constrained on /api/v1/providers/{id}/costs/filter-options (AWS Cost Explorer behavior). Selecting a service narrows the regions / accounts / tags returned in subsequent dimensions; each dimension excludes its own selections when computing its option list. No code changes required, but UIs that cache filter lists per session may want to refetch on selection change.
• New dimension query parameter on cost endpoints for filtering distinct values per dimension (service, account_id, region, tag_key, tag_value).
• New show_cost_as parameter on GET /api/v1/providers/{id}/costs/breakdown for switching the cost basis displayed.
• page_size limits raised on cost and recommendation list endpoints — see the per-endpoint parameter docs in API Reference.
• /api/v1/recommendations/{id}/details enriched with linked_to, comparison, and risk fields to match the data quality of the dashboard view.
• New linked_to field and search query param on GET /api/v1/providers/{id}/recommendations. linked_to exposes parent/child relationships between recommendations via the new LinkedTo schema (parent recs include their child recommendations' rolled-up monthly_savings).
• MoM and previous-month savings percentages now use a same-period comparison window — historical reports may show different percentage values, but the underlying monthly_savings totals are unchanged.

Go SDK changes

Sub-client renames to align with the API resource layout. Breaking — code using these names must be updated:

• client.Spending → client.Costs
• client.Savings → client.RecommendationsAudit

The Python and TypeScript SDKs already exposed client.costs (no rename needed there); the Go change brings naming parity across all three.

v0.2.0 - 2026-04-23

Resource renames

• spending → costs — The Spending resource is now Costs across API, SDKs, and docs. Endpoints moved from /api/v1/spending/* to /api/v1/costs/*. SDK clients use client.costs (Python, TypeScript) and client.Costs (Go). Existing SDK code written against client.spending will not compile; migrate to client.costs.
• savings → recommendations/audit — Realized-savings endpoints moved from /api/v1/savings/* to /api/v1/recommendations/audit/* to reflect that audits are a view of recommendation outcomes. SDK access is now client.recommendations.audit.*.

New API endpoints / SDK methods

Per-provider cost views for dashboards and filtered breakdowns:

• GET /api/v1/providers/{id}/costs/breakdown — Costs.ListByProvider (paginated, filterable, multi-group)
• GET /api/v1/providers/{id}/costs/summary — Costs.GetProviderSummary (KPIs + top 3 services)
• GET /api/v1/providers/{id}/costs/filter-options — Costs.GetProviderFilters (distinct values for autocomplete)
• GET /api/v1/providers/{id}/costs/timeline — Costs.GetProviderTimeline

Per-provider recommendation views:

• GET /api/v1/providers/{id}/recommendations/overview — Recommendations.GetProviderOverview (KPI header)
• GET /api/v1/providers/{id}/recommendations — Recommendations.ListByProvider (paginated list with filters)

Breakdown request — new capabilities

The ListByProvider cost breakdown supports:

• Multi-dimension group_by (service, account_id, region, tag)
• Date presets (30D, 6M, 12M) alongside explicit start/end
• Daily/monthly granularity
• Per-row previous-period cost and change percentage
• Per-date totals aggregated across all pages
• sort_by_date to sort by a specific date column

v0.1.0 - 2026-03-10

Initial release of LevelFour SDKs and API documentation.

API

• Standardized error responses across all endpoints
• Bearer auth via API keys (l4_live_ / l4_test_ prefixes)
• Offset-based pagination with x-fern-pagination support
• OpenAPI spec auto-generated from FastAPI

Python SDK (levelfour on PyPI)

• Sync (LevelFour) and async (AsyncLevelFour) clients
• API key validation and LEVELFOUR_API_KEY env var fallback
• Typed error hierarchy: AuthenticationError, NotFoundError, RateLimitError, etc.
• SyncPager / AsyncPager for automatic pagination
• WebhookVerifier for HMAC-SHA256 signature verification
• Per-request options via RequestOptions TypedDict

TypeScript SDK (levelfour on npm)

• LevelFourClient with full TypeScript type coverage
• Typed error classes: AuthenticationError, NotFoundError, RateLimitError, etc.
• Page async iterable for auto-pagination
• collectAll() helper for collecting all pages
• WebhookVerifier for signature verification
• HttpResponsePromise with .withRawResponse() for raw HTTP access

Go SDK (github.com/LevelFourAI/levelfour-go)

• levelfour.NewClient() with functional options pattern (WithBaseURL, WithMaxRetries, WithHTTPClient)
• Typed error structs with errors.As support
• Generic Page / PageIterator / CollectAll for pagination
• webhooks.Verifier for HMAC-SHA256 signature verification
• Per-request options via the option package

Documentation

• Developer portal with quickstart, SDK references, resource guides
• Auto-generated API reference from OpenAPI spec
• Guides for GitHub Actions and scheduled execution