Create a cost model
A cost model is what you pay a provider for one model: the units it is metered in, the dimensions that change the rate, and which of them your customer controls and which the provider controls. Send catalog_model to take all of that, and the rates, from the provider price catalog (source: catalog), and add overrides for your own negotiated or committed rates. Or send provider, model and a rate_card to enter the rates yourself (source: custom). Rates live on rate cards, so changing them never changes the model. In live mode an agent’s write is refused with 403 and proposal_required: put the same object in a config proposal. People change live configuration in the dashboard.
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Headers
Send true to see what the write would do without doing it. The response is the normal body with dry_run: true, changes (path, before, after), warnings and errors added, and nothing is stored. Validation runs as it would for a real write. The request is kept in request logs, tagged Dry run. When the same change is then made for real, its audit event has dry_run_preceded: true.
Request
Where the rates come from. Default catalog when catalog_model is sent, and custom otherwise.
Takes the provider, model, kind, units, dimensions and rates from this catalog model (catm_...), and follows its price versions from each effective_from. With it, leave out provider, model, kind, units, dimensions and rate_card. Use overrides to change a rate.
A custom cost model. The provider as trace() names it.
A custom cost model. The model ID as the provider names it, as trace() sends it.
What the model produces. Open: new values may be added.
A custom cost model. The first rates. Without effective_from the card is active from the moment the model is created, and a given effective_from can’t be in the past. In a configuration document, a rate_card adds a new version only when its rates differ from the latest, so applying the document twice changes nothing the second time.
Response
Where a cost model’s rates come from. catalog: the provider price catalog that Runledger maintains, with your overrides on top. custom: rate cards you enter yourself.
For source: catalog. The catalog model this cost model follows (catm_...).
What the model produces. Open: new values may be added.
The rate card in force now (rc_...). Left out until one is active.
Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.