Create a rate card
Adds a new version of a custom cost model’s rates. A cost model from the provider price catalog gets its rate cards from the catalog, and a request for one is refused with 409: use overrides instead. Send effective_from to schedule it, or leave it out to save a draft and activate it later. A rate card never changes once it is active: a new version replaces it from its own effective_from, and the response lists what differs from the version before (changes) and which price rules the change touches (affected_price_rules). A new version must start after every earlier version of the cost model, including any that is still scheduled, and effective_from can’t be in the past: either one returns 400 with parameter_invalid on effective_from. A new version applies only from its start date onward. Recorded usage is never repriced: it keeps the version that priced it. 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
The cost model (ID or key) these rates belong to.
When this version starts to price usage. It must be now or later, and after the start of every earlier version of the cost model, including a scheduled one. A new version applies only from this date onward. Recorded usage is never repriced: events and costs dated before it keep the earlier version. Leave it out to save a draft.
Response
draft: saved, not active. scheduled: becomes active at effective_from. active: in force. superseded: replaced by a later version.
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 price version these rates are (catp_...). Runledger creates one rate card for each catalog price version, with the same rates, effective_from, as_of and source. Your overrides are applied when a line is priced and are not part of the card.
For source: catalog. The catalog price version’s source.
For example price_rule_held, which says a rule set to hold keeps its current prices and so its margin falls or rises with the new costs.
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.