> For the complete documentation index, see [llms.txt](https://developer.fotokite.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.fotokite.com/~/changes/46/fotokite-api/handoff.md).
# Handoff
## Get handoff control status
> Returns the current handoff control status, including which client (Fotokite Live, Fotokite API, or Plugin) currently controls the system and which clients have requested control. Subscribing to this endpoint is recommended to receive real-time updates.
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"0.2.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname}:3128/api","description":"API service visible through NAT","variables":{"hostname":{"default":"sigma.local"}}}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v0/authentication/tokens/request","scopes":{"info":"Read static information about the system.","telemetry":"Read dynamic information about the system.","command":"Send commands to the system.","media":"Interaction with the media library.","internal":"Fotokite-internal APIs."}}}}},"schemas":{"HandoffControlStatus":{"type":"object","description":"Information about connected and controlling entities.","required":["controlling_client","requesting_clients"],"properties":{"controlling_client":{"$ref":"#/components/schemas/ClientHandoffStatus","nullable":true,"description":"Information about the entity currently controlling the system. If no entity is controlling the system, this field will be null.\n"},"requesting_clients":{"type":"array","items":{"$ref":"#/components/schemas/ClientHandoffStatus"}}}},"ClientHandoffStatus":{"type":"object","description":"Information about controlling entity or an entity requested control.","required":["session_name","operator_name"],"properties":{"plugin_id":{"type":"string","description":"Unique ID assigned by Fotokite assigned to this plugin.\n"},"plugin_name":{"type":"string","description":"Human readable name of the plugin. Has value of `Fotokite Live` for Fotokite Live application.\n"},"session_name":{"type":"string","description":"Name of the session for display to the operator if there can be multiple sessions per plugin.\n"},"operator_name":{"type":"string","description":"Operator name provided to `take_command` or `request_command` endpoint.\n"},"ip_address":{"type":"string","description":"IP address of the machine. Optional field used by Fotokite Tablets.\n"},"last_change":{"type":"string","format":"date-time","description":"Timestamp of the last change to this status. For controlling entity, this is the time when control was taken. For requesting entities, this is the time when the entity was added to the waiting queue.\n"}}}}},"paths":{"/v0/handoff/control/status":{"get":{"tags":["Handoff"],"summary":"Get handoff control status","description":"Returns the current handoff control status, including which client (Fotokite Live, Fotokite API, or Plugin) currently controls the system and which clients have requested control. Subscribing to this endpoint is recommended to receive real-time updates.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoffControlStatus"}}}}}}}}}
```
## Request control
> Requests control of the Fotokite system. If no other client (Fotokite Live, Fotokite API, Plugin) is controlling, control is granted. If another client is controlling, the request is added to the waiting list (requesting\_clients) in \`handoff/control/status\`. A request remains valid for 1 minute; clients should periodically re-request control. The result of the request must be monitored using the \`/handoff/control/status\` endpoint.
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"0.2.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname}:3128/api","description":"API service visible through NAT","variables":{"hostname":{"default":"sigma.local"}}}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v0/authentication/tokens/request","scopes":{"info":"Read static information about the system.","telemetry":"Read dynamic information about the system.","command":"Send commands to the system.","media":"Interaction with the media library.","internal":"Fotokite-internal APIs."}}}}},"schemas":{"RequestHandoffControl":{"type":"object","description":"Request to take control","required":["operator_name"],"properties":{"operator_name":{"type":"string","description":"Name of the operator taking control for display in UI.\n"},"ip_address":{"type":"string","description":"IP address of the machine taking control. Optional field used by Fotokite Tablets.\n"}}}}},"paths":{"/v0/handoff/control/request":{"post":{"tags":["Handoff"],"summary":"Request control","description":"Requests control of the Fotokite system. If no other client (Fotokite Live, Fotokite API, Plugin) is controlling, control is granted. If another client is controlling, the request is added to the waiting list (requesting_clients) in `handoff/control/status`. A request remains valid for 1 minute; clients should periodically re-request control. The result of the request must be monitored using the `/handoff/control/status` endpoint.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestHandoffControl"}}}},"responses":{"201":{"description":"Request to take control was accepted. This means that either the system is not controlled right now or the requestor already has control. Control will be revoked after 10 seconds. To prevent this, the requestor should periodically call `handoff/control/request`.\n"},"202":{"description":"Request was queued. This means that there is another entity controlling the system right now. The requestor should subscribe to the `handoff/control/status` endpoint or poll it to see the result of the request. It is also important to note that the request will be cleared after 1 minute if not taken.\n"}}}}}}
```
## Release control
> Releases control of the Fotokite system, allowing other clients (Fotokite Live, Fotokite API, or Plugin) to take control.
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"0.2.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname}:3128/api","description":"API service visible through NAT","variables":{"hostname":{"default":"sigma.local"}}}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v0/authentication/tokens/request","scopes":{"info":"Read static information about the system.","telemetry":"Read dynamic information about the system.","command":"Send commands to the system.","media":"Interaction with the media library.","internal":"Fotokite-internal APIs."}}}}}},"paths":{"/v0/handoff/control/release":{"post":{"tags":["Handoff"],"summary":"Release control","description":"Releases control of the Fotokite system, allowing other clients (Fotokite Live, Fotokite API, or Plugin) to take control.\n","responses":{"204":{"description":"Success, command released.\n"}}}}}}
```
## Override control
> Immediately enforces control of the Fotokite system, overriding other clients (Fotokite Live, Fotokite API, or Plugin) that may be blocking access. This endpoint is intended for use mainly by Fotokite Live.
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"0.2.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname}:3128/api","description":"API service visible through NAT","variables":{"hostname":{"default":"sigma.local"}}}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v0/authentication/tokens/request","scopes":{"info":"Read static information about the system.","telemetry":"Read dynamic information about the system.","command":"Send commands to the system.","media":"Interaction with the media library.","internal":"Fotokite-internal APIs."}}}}},"schemas":{"RequestHandoffControl":{"type":"object","description":"Request to take control","required":["operator_name"],"properties":{"operator_name":{"type":"string","description":"Name of the operator taking control for display in UI.\n"},"ip_address":{"type":"string","description":"IP address of the machine taking control. Optional field used by Fotokite Tablets.\n"}}},"Error":{"type":"object","description":"A generic error object.","required":["code","message"],"properties":{"code":{"description":"Unique error code.","type":"string"},"message":{"description":"User readable message of the error","type":"string"}}}}},"paths":{"/v0/handoff/control/override":{"post":{"tags":["Handoff"],"summary":"Override control","description":"Immediately enforces control of the Fotokite system, overriding other clients (Fotokite Live, Fotokite API, or Plugin) that may be blocking access. This endpoint is intended for use mainly by Fotokite Live.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestHandoffControl"}}}},"responses":{"201":{"description":"Success, command taken.\n"},"403":{"description":"Failure, current session can't command the system right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://developer.fotokite.com/~/changes/46/fotokite-api/handoff.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.