diff --git a/v2:-Documentation.md b/v2:-Documentation.md index 88660e7..a3eb188 100644 --- a/v2:-Documentation.md +++ b/v2:-Documentation.md @@ -200,18 +200,28 @@ Default address: `localhost:2019` ## POST /load -Sets Caddy's configuration to the JSON body. The `Content-Type` header must indicate a JSON payload, e.g. `application/json`. Configuration changes are very lightweight and efficient. +Sets Caddy's configuration. The response blocks until the reload completes or fails. Configuration changes are lightweight, efficient, and incur zero downtime. -_Note for Enterprise users_: If you are using the `/config/` endpoint to modify configuration instead, you MUST NOT use `/load` because it lacks the capabilities for partial configuration changes. +The request's Content-Type header indiciates the config format provided in the request body. Usually, this should be `application/json` which represents Caddy's native config format. For another config format, specify the appropriate Content-Type so that the value after the forward slash `/` is the name of the config adapter to use. For example, when submitting a Caddyfile, use a value ending in `/caddyfile`; or for JSON 5, specify a value ending in `/json5`; etc. + +_Note for Enterprise users_: If you use the `/config/` endpoint to modify configuration, you MUST NOT mix its use with `/load` because `/load` lacks the capabilities for partial configuration changes, and mixing their use could lead to inconsistent configuration states. ### Example ```bash $ curl -X POST "http://localhost:2019/load" \ - -H "Content-Type: application/json" + -H "Content-Type: application/json" \ -d @caddy.json ``` +**Note:** curl's `-d` flag removes newlines, so if your config format is sensitive to line breaks (e.g. the Caddyfile), use `--data-binary` instead: + +```bash +$ curl -X POST "http://localhost:2019/load" \ + -H "Content-Type: text/caddyfile" \ + --data-binary @Caddyfile +``` + ## POST /stop Gracefully shuts down the server. @@ -629,7 +639,7 @@ reverse_proxy [] [] { unhealthy_status unhealthy_latency - # header manipulation + # header manipulation header_up [+|-] [ []] header_down [+|-] [ []]