Vibe Costs

Technical reference / v0.1

A narrow cost feed an engineer—or agent—can implement.

Start with one consented account and one honest current-period total. Add attribution and events only when the provider ledger supports them.

01 / Interface

Three reads. One permission.

Existing provider conventions are welcome. These canonical paths describe the semantics, not a required URL layout.

GET/.well-known/oauth-authorization-serverOAuth discovery and costs:read scope
GET/v1/cost-accountsOnly billing accounts selected during consent
GET/v1/costsCurrent-period or historical incurred cost

02 / Authorization

Provider-hosted OAuth first.

Use authorization code with PKCE S256, exact production redirect URIs, short-lived access tokens, renewal, revocation, and account selection during consent.

The costs:read grant is the only resource permission in this profile. Standard identity or renewal scopes such as openid or offline_access may accompany it when the provider requires them.

The grant must not authorize deployments, inference, customer data, members, plans, payment methods, or secrets.

A revocable restricted token carrying only cost-read permission is an acceptable transitional profile.

Minimum valid responseapplication/json
{
  "cost_account_id": "acct_123",
  "billing_currency": "USD",
  "period_start": "2026-08-01T00:00:00Z",
  "period_end": "2026-08-21T00:00:00Z",
  "cost_status": "estimated",
  "billed_cost": "37.37",
  "updated_at": "2026-08-21T13:45:00Z",
  "items": []
}

03 / Semantics

Preserve what the ledger knows.

Money
Base-10 JSON strings; never binary floating-point values.
Time
RFC 3339 UTC. Start is inclusive; end is exclusive.
Freshness
updated_at records provider calculation time, not fetch time.
Status
Open periods are estimated. Final records change only through explicit corrections.
Billed cost
Invoice-basis cost after reduced rates and discounts; credits remain signed.
Effective cost
Optional FOCUS amortized cost; never use it as a synonym for billed cost.
Currency
Use ISO 4217 and never silently convert or infer from locale.

04 / Ship checklist

A reviewable pilot, not a platform rewrite.

Core response conformance can ship before itemized attribution. Events remain outside the v0.1 machine-readable profile.

  1. 01Choose the authoritative provider ledger and document its calculation delay.
  2. 02Create costs:read as a permission that cannot mutate resources or billing settings.
  3. 03Return consented cost accounts with stable opaque IDs, currency, and billing time zone.
  4. 04Return invoice-basis billed cost as decimal strings with estimated/final status and updated_at.
  5. 05Preserve credits, refunds, negative adjustments, and provider-specific finalization.
  6. 06Add snapshot-bound pagination, conditional caching, documented rate limits, Retry-After behavior, and conventional errors.
  7. 07Validate responses against the published schema and positive and negative CI-tested cases.

Reference consumer

We build the connector.

Vibe Costs will implement and maintain the consumer integration, validate it against a customer-owned account, respect provider rate limits and revocation, and identify it as verified only after accuracy testing.

Review securityOpenAPI