Activate a rate card
Makes a draft rate card the active version from effective_from (default now, or a later time, never in the past, and after every earlier version of the cost model, or the call returns 400 with parameter_invalid on effective_from). The version it replaces becomes superseded at that time. Costs recorded before then keep the version that priced them, and nothing already recorded is repriced. Price rules set to hold keep their current prices, and the response says so in warnings. The rate_card.activated webhook fires when the card becomes active. 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.
Path parameters
The rate card ID (rc_...).
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
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.