usage

usage is one of the estate's 317 automotive nouns — a job a car needs done. It carries 3 capabilities: 2 live, 1 sandbox, 0 declared · doors apis.vin · aggregator.vin.

Identity

Lifecycle

Usage — UsageStatus: 3 states, 3 transitions — open · capped · reset. Each transition is a past-tense event on the record.

Events

The vocabulary this noun can append to the record — 3 past-tense, versioned event types, each linked to the capability that emits it:

• Usage.capped@1 — emitted by meter
• Usage.metered@1 — emitted by meter
• Usage.reset@1 — emitted by meter

Discover & read

read

usage.read · GET /usages/read · gate none · sandbox · answers UsageRead@1

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /5XYP6DGC0SG586605 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

import { usage } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await usage.read({"subject":"subject","window":"window"})

curl 'https://apis.vin/usages/read?subject=subject&window=window'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

{
  "type": "OK",
  "answers": "UsageRead@1",
  "value": {
    "key": "vk_sandbox_891cfe4f",
    "period": "2026-08",
    "metered": {
      "calls": 278,
      "amount": {
        "amount": "278",
        "currency": "USD"
      }
    },
    "ceiling": {
      "period": "day",
      "amount": {
        "amount": "2500",
        "currency": "USD"
      }
    },
    "remaining": {
      "amount": "2222",
      "currency": "USD"
    },
    "priceTable": "https://apis.vin/.well-known/agents.json#pricing",
    "resetAt": "2026-09-01T00:00:00.000Z",
    "capped": false,
    "status": "open"
  },
  "evidence": {
    "key": "vk_sandbox_891cfe4f",
    "period": "2026-08",
    "metered": {
      "calls": 278,
      "amount": {
        "amount": "278",
        "currency": "USD"
      }
    },
    "ceiling": {
      "period": "day",
      "amount": {
        "amount": "2500",
        "currency": "USD"
      }
    },
    "remaining": {
      "amount": "2222",
      "currency": "USD"
    },
    "priceTable": "https://apis.vin/.well-known/agents.json#pricing",
    "resetAt": "2026-09-01T00:00:00.000Z",
    "capped": false,
    "status": "open"
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "governance-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

get

usage.get · GET /usages/get · gate key · live · answers Usage@1

Promoted — earned its own page: /catalog/usage.get (computed on every regen: live on the wire + carries its own stateSet).

No input — this capability takes no request body.

Door — apis.vin serves this noun on its two routes: / (the landing) · /5XYP6DGC0SG586605 (the VIN lens).

Try it — live: answers on the wire today. A sandbox key still selects the deterministic simulated mode — drive the full outcome range with the magic triggers.

import { usage } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await usage.get()

curl 'https://apis.vin/usages/get'

More actions

meter

usage.meter · POST /usages/meter · gate key · live · answers UsageMeter@1

Promoted — earned its own page: /catalog/usage.meter (computed on every regen: live on the wire + carries its own stateSet).

No input — this capability takes no request body.

Door — apis.vin serves this noun on its two routes: / (the landing) · /5XYP6DGC0SG586605 (the VIN lens).

Try it — live: answers on the wire today. A sandbox key still selects the deterministic simulated mode — drive the full outcome range with the magic triggers.

Emits — Usage.capped@1 · Usage.metered@1 · Usage.reset@1.

import { usage } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await usage.meter()

curl -X POST https://apis.vin/usages/meter \
  -H 'content-type: application/json' \
  -d '{}'

Data model

The record shape behind this noun — one entity, each property an evidence field. See the whole estate model on the data model page.

Usage

Schema

Modeled

The noun drawn out — its record shape, its lifecycle, and how it is exercised end to end. 6 diagrams, rendered from the estate model.

Usage · Class model

Usage · State machine

Usage · Class model

Usage · State machine

Usage · Class model

Usage · State machine

Generated from the catalog. Every capability, answer, gate, and entity on this page is a rendered descriptor — it cannot drift from the wire.