POST /registry/wind_downStamps a deadline on placement rows and queues a wind_down control message to each owner, so it can save and let go early. At the deadline the row counts as free and the next request re-places the id. The deadline lives on the row: it survives the owner's death and is re-sent to a replacement owner.
Authentication
pinboard:operator scope. namespace (and, hostname-aware, env) must be inside the claim. Each row is also judged on its owner's hostname and env; rows outside the claim are skipped (namespace-wide) or answer 403 (single id).
Request body
application/json, at most 1 MiB.
| Field | Type | Required | Description |
|---|---|---|---|
namespace | string | Yes | Namespace, for example /threads. |
id | string | No | One instance. Omitted: every placement in the (env, namespace). |
deadline | number | null | Yes | Seconds from now. Floored to one lease (15 s by default). null revokes a pending wind-down. |
env | string | Hostname-aware: yes | Env whose placements to wind down. Rejected in single-hostname mode. |
Example
curl -X POST https://pinboard.example.com/registry/wind_down \
-H "Authorization: Bearer $PINBOARD_OPERATOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"namespace": "/threads", "id": "t_8f2a", "deadline": 30}'Response
200
| Field | Type | Description |
|---|---|---|
queued | boolean | With id: true when the id was placed and its owner was notified, false when it was not placed. |
queued | integer | Without id: rows stamped. |
{ "queued": true }Errors
| Status | Body | When |
|---|---|---|
401 | {"error":"unauthorized"} | No accepted credential |
403 | {"error":"forbidden"} | No pinboard:operator scope, malformed claim, or (with id) the row's owner is outside the claim |
503 | {"error":"not the serving fleet"} | Node not serving |
413 / 400 | body too large / invalid json | |
403 | {"error":"namespace not allowed: …"} | Namespace outside the claim |
403 | {"error":"env not allowed: …"} | Hostname-aware, env outside the claim |
400 | {"error":"expected { namespace, id?, deadline }"} | Schema failure. Hostname-aware: expected { namespace, id?, deadline, env }. |
400 | {"error":"namespace must be '/' plus a single path segment: \"…\""} | Malformed namespace |
400 | {"error":"env is required in hostname-aware mode"} | |
400 | {"error":"env requires hostname-aware mode"} | |
400 | {"error":"invalid env: \"…\""} | Bad characters or * |
With id, an unplaced id answers queued: false before the scope check runs.