Unreserve

Release one or more held resources so other requesters can claim them.

Endpoint

POST /api/v1/Reservation/unreserve
X-Api-Key: YOUR_API_KEY
Content-Type: application/json

Request fields

Field	Type	Required	Description
`requester`	string	Yes	Must match the requester that made the original reserve call.
`resource`	string	Yes	The resource to release.
`releaseToken`	string	Yes	The token returned by the reserve call. Prevents other requesters from releasing a lock they don't hold.

Example request

[
  {
    "requester":    "worker-1",
    "resource":     "job-42",
    "releaseToken": "a3f8c2d1-4b5e-..."
  }
]

Response fields

Field	Type	Description
`resource`	string	The resource that was operated on.
`requester`	string	The requester from your request.
`status`	string	Outcome — see statuses below.
`explanation`	string	Human-readable detail.
`released`	array or null	All physical resources freed by this call — includes the slot and any co-released blockers.

Example response

[
  {
    "resource":    "job-42",
    "requester":   "worker-1",
    "status":      "RELINQUISHED",
    "explanation": "RELINQUISHED",
    "released":    ["job-42"]
  }
]

Statuses

Status	Meaning
`RELINQUISHED`	Successfully released.
`NOT_RESERVED`	The resource was not held by anyone. Treated as success — safe to call on an already-free resource.
`DOESNT_OWN_RESERVATION`	The requester does not hold this resource (another requester does). The call is rejected.

The release token

The releaseToken is a server-generated UUID returned by the reserve call. It ensures that only the entity that made the reservation can release it — passing a wrong or missing token returns HTTP 403.

If you lose a release token, you have two options:

Force-release from the dashboard (no token required) — your own reservations only
Wait for the TTL to expire, if one was set

Releasing a resource you don't hold

Calling unreserve on a resource that is not currently reserved returns NOT_RESERVED with a 200 OK — this is intentionally safe and idempotent. Calling unreserve on a resource held by a different requester returns DOESNT_OWN_RESERVATION and the release is rejected.

Releasing all resources for a requester

To bulk-release everything a requester holds (e.g. on process shutdown), use:

DELETE /api/v1/Reservation/requester/{requester}
X-Api-Key: YOUR_API_KEY

This bypasses the token check — it is scoped to your own tenant and requester.

{"requester": "worker-1", "released": 3}

Force-unreserve from the dashboard

Dashboard users can force-release any reservation within their own tenant without a release token via POST /api/v1/Tenant/force-unreserve. This is only available from the authenticated dashboard session.

Error codes

HTTP status	When
`400`	Empty body, or missing `requester` / `resource`.
`401`	Missing or invalid `X-Api-Key`.
`403`	One or more requests supplied an invalid or missing release token. The response body still contains per-item results.
`429`	Daily operation limit reached. Check `Retry-After` header.