POST /registry/tagSets a free-form owner tag on one placement row, for example ws:W for a workspace. Operators filter the fleet overview by it. The tag is written only while the row is owned by the quoted session at the quoted epoch.
The tag stays through reclaim on re-register and through wind-down. It is gone once the row is released or the id re-places.
Authentication
pinboard:worker scope, same account that registered the session; the namespace must be inside the claim.
Request body
application/json, at most 1 MiB.
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | Yes | Owning session. |
namespace | string | Yes | Namespace the session registered. |
id | string | Yes | Instance id. |
epoch | string | Yes | Decimal digits: the placement epoch held. |
tag | string | Yes | 1–256 characters. Replaces any previous tag. |
Example
curl -X POST https://pinboard.example.com/registry/tag \
-H "Authorization: Bearer $PINBOARD_WORKER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "3f9c0d6e2b1a4c7d8e9f0a1b2c3d4e5f",
"namespace": "/threads",
"id": "t_8f2a",
"epoch": "1762560000123",
"tag": "ws:acme"
}'Response
200
| Field | Type | Description |
|---|---|---|
tagged | boolean | true when written. false when the row is absent or held by another session or epoch. |
{ "tagged": true }Errors
| Status | Body | When |
|---|---|---|
401 | {"error":"unauthorized"} | No accepted credential |
403 | {"error":"forbidden"} | Missing scope, another account's session, or 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, tag }"} | Schema failure, including an empty or over-long tag |
400 | {"error":"invalid namespace"} | Malformed namespace |
400 | {"error":"namespace not registered: …"} | The session did not register that namespace |
409 | {"error":"unknown session","reregister":true} | Session unknown or lease expired |