Update a margin guardrail
Changes the floor, the action, the scope or whether it is enabled. 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 margin guardrail ID (mg_...) or its key.
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
expected: the margin the work should have, from its price and its expected cost at check() time. realized: confirmed revenue minus cost over the trailing window for the work the guardrail covers, as the margin report counts it, so reversals lower it.
The lowest margin allowed, as a decimal from 0 to 1 of the price. "0.25" is 25%. Negative values are not accepted.
warn adds warnings and a webhook. block also denies in check().
An ISO 8601 duration. For realized, the trailing range the margin is read over. For expected, the range the observed average cost is read over when check() has no estimated_usage. Default P7D.
Response
expected: the margin the work should have, from its price and its expected cost at check() time. realized: confirmed revenue minus cost over the trailing window for the work the guardrail covers, as the margin report counts it, so reversals lower it.
warn adds warnings and a webhook. block also denies in check().
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.