A valid request URL is required to generate request examples{
"lease": {
"holder": {
"kind": "api_key",
"viaCopilot": true,
"userId": "<string>",
"apiKeyId": "<string>",
"onBehalfOf": {
"kind": "schedule",
"scheduleId": "<string>",
"userId": "<string>",
"apiKeyId": "<string>"
}
},
"expiresAt": "2023-11-07T05:31:56Z"
},
"run": {
"runId": "<string>",
"agentRunId": "<string>",
"goal": "<string>",
"state": "queued",
"stepSeq": 123,
"initiator": {
"kind": "api_key",
"viaCopilot": true,
"userId": "<string>",
"apiKeyId": "<string>",
"onBehalfOf": {
"kind": "schedule",
"scheduleId": "<string>",
"userId": "<string>",
"apiKeyId": "<string>"
}
},
"recovery": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"since": "2023-11-07T05:31:56Z",
"remainingMs": 4503599627370495,
"blockedReason": null
}
},
"people": [
{
"userId": "<string>",
"lastActionAt": "2023-11-07T05:31:56Z"
}
],
"agentLastActionAt": "2023-11-07T05:31:56Z"
}{
"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": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Who is driving a device
One read for the question a Control view asks after every gesture: is an agent on this device, is a colleague, and whose lease is it under.
lease is your organisation’s live lease and who inside it holds it, or null; another organisation’s lease reads as none, exactly as it does on GET /v1/leases. run is the run driving the device right now, or null once it has finished. people are the people other than you who acted on the device in the last sixty seconds, and agentLastActionAt is when an agent last did.
It joins three things devices:read can already read one route at a time, and adds nothing to them: no lease id, no run token, and never a name. A device your organisation does not own, or one outside your key’s narrowing, answers 404 exactly as an id that never existed does. An offline device still answers: this route asks who is driving, not whether the phone is reachable.
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{
"lease": {
"holder": {
"kind": "api_key",
"viaCopilot": true,
"userId": "<string>",
"apiKeyId": "<string>",
"onBehalfOf": {
"kind": "schedule",
"scheduleId": "<string>",
"userId": "<string>",
"apiKeyId": "<string>"
}
},
"expiresAt": "2023-11-07T05:31:56Z"
},
"run": {
"runId": "<string>",
"agentRunId": "<string>",
"goal": "<string>",
"state": "queued",
"stepSeq": 123,
"initiator": {
"kind": "api_key",
"viaCopilot": true,
"userId": "<string>",
"apiKeyId": "<string>",
"onBehalfOf": {
"kind": "schedule",
"scheduleId": "<string>",
"userId": "<string>",
"apiKeyId": "<string>"
}
},
"recovery": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"since": "2023-11-07T05:31:56Z",
"remainingMs": 4503599627370495,
"blockedReason": null
}
},
"people": [
{
"userId": "<string>",
"lastActionAt": "2023-11-07T05:31:56Z"
}
],
"agentLastActionAt": "2023-11-07T05:31:56Z"
}{
"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": "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
Who is driving.
Who is driving one device: the lease's holder, the run on it, and the people who acted recently. One read for the question a Control view asks after every gesture.
Your organisation's live lease on the device and who inside it holds the lease, or null when it holds none.
Show child attributes
Show child attributes
The run driving the device right now, or null. A finished run is not driving.
Show child attributes
Show child attributes
People other than you with an action on the device in the last sixty seconds, newest first. Ids, never names: resolve them through your own directory.
Show child attributes
Show child attributes
When an agent (a run, a key or a copilot) last acted on the device within the same window, or null.