Replace the configuration
Imports a configuration document by replacing the sections it carries, going through validation first. For each section the document carries, objects in the account that are missing from it are removed, and a section the document leaves out is untouched. The changes of a dry run list each removal (a change with before and no after) before anything is applied. if_match must be the hash you read, so a change made in between is not overwritten. A stale if_match, one that no longer matches the current configuration, returns 409 with invalid_state and applies nothing: read GET /v1/config again, merge your change into what is there, and send the new hash. With a sandbox key the change is applied at once. With a live key it is not applied: an import is always a proposal, so Runledger creates a config proposal that a signed-in Admin must accept, and returns it. To add and update without removing anything, use POST /v1/config/apply. Needs config:write, or config:propose for live keys.
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
Everything an agent or person configures, in the shape the create requests take. Leave a section out to leave it alone. Objects with a key are matched by key, webhook endpoints by url. Routing rules and notification rules are ordered lists that replace the current ones. Payment providers are connected with POST /v1/payment_providers, because a person completes that step.
The hash of the configuration this document was based on. A stale one returns 409 with invalid_state.
Response
What was created or changed. Only when applied.
The configuration’s hash after the change. Only when applied.
The config proposal ID. Only when proposed.