curl --request POST \
--url https://api.example.com/api/config/reload \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"targets": [
"<string>"
]
}
'import requests
url = "https://api.example.com/api/config/reload"
payload = { "targets": ["<string>"] }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({targets: ['<string>']})
};
fetch('https://api.example.com/api/config/reload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/config/reload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'targets' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/config/reload"
payload := strings.NewReader("{\n \"targets\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/config/reload")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"targets\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/config/reload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"targets\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"ok": true,
"op": "<string>",
"awaiting_respawn": [
{
"keys": [
"<string>"
],
"name": "<string>"
}
],
"error": "<string>",
"local_only": false,
"reachable": true,
"recycle": {
"fresh": [
{
"generation": 123,
"kind": "<string>",
"name": "<string>"
}
],
"recycle": [
{
"generation_before": 123,
"keys": [
"<string>"
],
"kind": "<string>",
"name": "<string>",
"status": "<string>",
"detail": "<string>"
}
],
"skipped": [
"<string>"
],
"recycle_stopped": {
"detail": "<string>",
"kind": "<string>",
"name": "<string>"
}
},
"results": [
{
"name": "<string>",
"outcome": "applied",
"detail": "<string>",
"error": "<string>",
"payload": null
}
],
"roll_deferred": false,
"roll_deferred_to": "<string>"
}
}{
"error": "<string>",
"code": "<string>"
}{
"error": "reloading — the server is applying a config reload; retry shortly",
"reloading": true
}Soft-restart the fleet from its manifest, restarting the drifted workers whose reload built
Soft-restart the fleet from its manifest, then restart the workers whose env needs a restart.
Refreshes env from the config manager, resets every settings cache, and re-initializes from the
manifest, in-process. Applied on this worker (when it is a target) and broadcast to the fleet (all
workers, or only targets); the response embeds the per-worker fleet report.
Heavy (a full re-init); meant for env/config saves, not tool edits. A convergence op: its whole purpose is aligning siblings to persisted state, so a failed local reload still broadcasts and then re-raises with the fleet report attached.
Called over MCP on a worker the reload applies to (no targets, or targets naming that
worker), the reload answers on the session that called it and then retires that session with the
generation it ran on: a later call on the same session fails (streamable HTTP answers it 404, and an
SSE session’s stream closes), so the client starts a new session to go on. When targets leave
that worker out, nothing reloads there and the session keeps working.
An applied worker’s payload is {status: "ok", env_keys, awaiting_respawn}; a worker whose
reload was refused at its epoch build (the build discarded before its swap) replies failed
with {status: "discarded", awaiting_respawn}, serving its previous epoch with that drift
standing; any other failed reload, a failed discard among them, carries no payload.
awaiting_respawn names the recycle-class keys whose value now differs from the one that
worker bound (at boot, or when the plugin that declares them was loaded) — the soft restart
carries every hot key in place, and those keys take effect only on a restart. Once the reports
are in, every worker the reload addressed that names such a key is restarted one at a time
through the deployment’s supervisor, except a worker whose reload was refused at its epoch
build: the stored config did not build on it and a restart may fail the same way, so it keeps
serving its current config and is named in awaiting_respawn. Any worker other than this one
whose state is unknown (its reload failed otherwise or did not finish, it has no row, its reply
carries no awaiting_respawn list, or the bus was unreachable) is asked once it is ready and
restarted unless its reply confirms it clean or states a refused build (its restart then
withheld); the workers that confirmed none are left running. This worker is never asked: when
its own state is unknown, it needs its own restart. recycle reports that roll (null when
the roll had no worker to visit: every addressed worker confirmed no recycle-class key, or the
only ones naming one were refused at their epoch build) and awaiting_respawn the workers
still awaiting a respawn after it. When this worker needs its own restart and the roll
converged, it exits gracefully once the reply is answered and its supervisor starts it again. A
soft restart run under a bound the roll’s waits can outlast (a dispatched job’s budget, an armed
turn budget) runs no roll itself: it hands the roll to the bus member it acts for, which carries
it out after the reply and departs itself last, once the roll converged, when it needs its own
restart; roll_deferred is then true, roll_deferred_to names that member, recycle is null and
awaiting_respawn empty, the roll not judged in this reply. Otherwise roll_deferred is
false and roll_deferred_to null.
curl --request POST \
--url https://api.example.com/api/config/reload \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"targets": [
"<string>"
]
}
'import requests
url = "https://api.example.com/api/config/reload"
payload = { "targets": ["<string>"] }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({targets: ['<string>']})
};
fetch('https://api.example.com/api/config/reload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/config/reload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'targets' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/config/reload"
payload := strings.NewReader("{\n \"targets\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/config/reload")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"targets\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/config/reload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"targets\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"ok": true,
"op": "<string>",
"awaiting_respawn": [
{
"keys": [
"<string>"
],
"name": "<string>"
}
],
"error": "<string>",
"local_only": false,
"reachable": true,
"recycle": {
"fresh": [
{
"generation": 123,
"kind": "<string>",
"name": "<string>"
}
],
"recycle": [
{
"generation_before": 123,
"keys": [
"<string>"
],
"kind": "<string>",
"name": "<string>",
"status": "<string>",
"detail": "<string>"
}
],
"skipped": [
"<string>"
],
"recycle_stopped": {
"detail": "<string>",
"kind": "<string>",
"name": "<string>"
}
},
"results": [
{
"name": "<string>",
"outcome": "applied",
"detail": "<string>",
"error": "<string>",
"payload": null
}
],
"roll_deferred": false,
"roll_deferred_to": "<string>"
}
}{
"error": "<string>",
"code": "<string>"
}{
"error": "reloading — the server is applying a config reload; retry shortly",
"reloading": true
}Authorizations
Body
A local reload-config request.
An optional targets list restricts the fan-out of the soft-restart to named workers (all workers
when omitted).
Response
Success.
A fleet soft restart's per-worker reload report, the recycle roll it ran, and its verdict.
An applied worker's payload is {status: "ok", env_keys, awaiting_respawn}; a worker
whose reload was refused at its epoch build (the build discarded before its swap) replies
failed with {status: "discarded", awaiting_respawn}, serving its previous epoch with
that drift standing; any other failed reload, a failed discard among them, carries no payload.
recycle is the roll that restarted the workers the reload addressed whose reload built and
whose awaiting_respawn named a recycle-class key, or whose state was unknown: a worker other
than the answering one is asked once ready and restarted when its reply neither confirms it
clean nor states a refused build; the answering worker is never asked, and when its own state is
unknown its restart is its self-deferred line, present when the roll converged. A worker
whose reload was refused at its epoch build is never restarted: the stored config did not build
on it and a restart may fail the same way, so the roll leaves it running and lists it.
recycle is null when the roll had no worker to visit: every addressed worker confirmed
no recycle-class key, or the only ones naming one were refused at their epoch build.
awaiting_respawn the workers still awaiting a respawn after the roll (name + keys), those
left running after a refused epoch build among them. roll_deferred is true when the roll
was handed to the worker roll_deferred_to names, which carries it out after the reply
(recycle is null and awaiting_respawn empty); roll_deferred_to is null
otherwise.
Show child attributes
Show child attributes