POST /registry/releaseDeletes placement rows so the next request for those ids places afresh. A row is deleted only while it is still owned by the quoted session at the quoted epoch, so a late release never frees a newer placement. Workers call this when an instance is evicted or shuts down.
Authentication
pinboard:worker scope, same account that registered each session. Every quoted session's namespace must be inside the principal's claim.
Request body
application/json, at most 1 MiB. A non-empty array:
| Field | Type | Required | Description |
|---|---|---|---|
[].sessionId | string | Yes | Session that owns the row. |
[].namespace | string | Yes | Namespace, for example /threads. Must be one the session registered. |
[].id | string | Yes | Instance id. |
[].epoch | string | No | Decimal digits: the placement epoch the worker holds (its Pinboard-Epoch). Omitted: matches only a row without an epoch. |
Always send epoch. Rows placed through routing always have one, so an entry without it frees nothing in practice.
Items may mix sessions and namespaces. All are validated before any row is deleted: one bad item fails the whole call and frees nothing.
Example
curl -X POST https://pinboard.example.com/registry/release \
-H "Authorization: Bearer $PINBOARD_WORKER_TOKEN" \
-H "Content-Type: application/json" \
-d '[
{"sessionId": "3f9c0d6e2b1a4c7d8e9f0a1b2c3d4e5f", "namespace": "/threads", "id": "t_8f2a", "epoch": "1762560000123"}
]'Response
200
| Field | Type | Description |
|---|---|---|
released | integer | Rows deleted. Rows already gone or owned elsewhere count 0. |
{ "released": 1 }Errors
| Status | Body | When |
|---|---|---|
401 | {"error":"unauthorized"} | No accepted credential |
403 | {"error":"forbidden"} | Missing scope, another account's session, or a namespace outside the claim |
503 | {"error":"not the serving fleet"} | Node not serving |
413 / 400 | body too large / invalid json | |
400 | {"error":"expected [{ sessionId, namespace, id, epoch? }]"} | Not a non-empty array of valid items, or epoch not digits |
400 | {"error":"invalid namespace"} | Malformed namespace |
400 | {"error":"namespace not registered: …"} | The session did not register that namespace |
409 | {"error":"unknown session","reregister":true} | A quoted session is unknown or its lease expired |
A session whose lease has lapsed cannot release; its rows are freed by dead-owner eviction on the next request.