A valid request URL is required to generate request examples{
"deviceId": "<string>",
"leaseId": "<string>",
"acquiredAt": "<string>",
"expiresAt": "<string>"
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Take a device
Claim exclusive use of a device and get a lease back. Send the leaseId on every gesture and on the release; leases expire on their own after ten minutes, so renew if you are still working.
A REFUSAL DOES NOT SAY WHY, and that is deliberate. Someone else holding it, a spent quota and an unreachable device all answer the same way, because a caller that could tell them apart would have a running commentary on the organisation’s device state and its quota. GET /v1/devices says the same thing from the other side: online is not a promise you can take it.
This is the REST counterpart of the acquire_device tool and runs the same lifecycle call, so the two faces cannot disagree about who may take what.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"deviceId": "<string>",
"leaseId": "<string>",
"acquiredAt": "<string>",
"expiresAt": "<string>"
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Path Parameters
The deviceId from a listing.
Response
The device is yours until expiresAt.
A lease you hold. The fencing token is deliberately absent: it is the token the device itself checks to shut out a stale holder, it is stamped on your calls for you, and a client has no use for it.
The device you now hold.
The lease id. Send it on every action and on the release, and treat it as a credential: it is what identifies the holder, so anyone who has it can act as you and can give the device back. This is the only response that returns it, and it is returned to the caller that just took the lease.
ISO-8601 instant the lease was granted.
ISO-8601 instant after which the lease no longer holds the device. Renew before it passes.