> 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/fotokite-api/handoff.md).

# Handoff

## Get handoff control state

> Returns the current handoff control state, 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.<br>

```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":["read"]}],"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/v1/auth/token/request","scopes":{"read":"Grants access to retrieve system data and information.","control":"Allows sending commands to control the system.","can_override":"Allows to make `handoff/control/override` call to override current controlling client.","experimental":"Enables access to experimental API features.","internal":"Fotokite-internal functions. Not for third-party use."}}}}},"schemas":{"HandoffState":{"type":"object","description":"Information about connected and controlling entities.","required":["controlling_client","requesting_clients"],"properties":{"controlling_client":{"$ref":"#/components/schemas/ControllingClient","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/RequestingClient"}}}},"ControllingClient":{"nullable":true,"type":"object","description":"Information about controlling entity.","required":["session_id","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_id":{"type":"string","description":"Unique ID of the session controlling control.\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"},"last_change":{"type":"string","format":"date-time","description":"Time when control was taken.\n"}}},"RequestingClient":{"type":"object","description":"Information about requested control client.","required":["session_id","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_id":{"type":"string","description":"Unique ID of the session requested control.\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"},"last_change":{"type":"string","format":"date-time","description":"Time when the entity was added to the waiting queue.\n"}}}}},"paths":{"/v1/handoff/state":{"get":{"tags":["Handoff"],"summary":"Get handoff control state","description":"Returns the current handoff control state, 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/HandoffState"}}}}}}}}}
```

## 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.<br>

```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":["control"]}],"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/v1/auth/token/request","scopes":{"read":"Grants access to retrieve system data and information.","control":"Allows sending commands to control the system.","can_override":"Allows to make `handoff/control/override` call to override current controlling client.","experimental":"Enables access to experimental API features.","internal":"Fotokite-internal functions. Not for third-party use."}}}}},"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"},"regulatory_mode":{"$ref":"#/components/schemas/OperatorRegulatoryMode"},"operator_gps_lat":{"description":"Latitude of the operator reported by GPS [-90..+90] (degrees)","type":"number","minimum":-90,"exclusiveMinimum":true,"maximum":90},"operator_gps_lon":{"description":"Longitude of the operator reported by GPS (-180..+180] (degrees)","type":"number","minimum":-180,"exclusiveMinimum":true,"maximum":180},"operator_gps_elevation":{"description":"Elevation of the operator reported by GPS (meters)","type":"number"},"operator_gps_accuracy":{"description":"Operator GPS accuracy in meters","type":"number","minimum":0}}},"OperatorRegulatoryMode":{"type":"string","description":"DroneID regulation variant that the UI provided to the operator complies with.\n\nDroneID broadcasts such as those required for FAA RemoteID contain information about the UAS operator. This endpoint can be used to provide such information. An update must be provided regularly according to the applicable regulation to prevent entering a DroneID error state (this may require sending handoff requests more frequently than it is required normally).\n\nBy setting this value, you declare compliance with the relevant regulation.\n\nFor the US:\n*  An operator location of sufficient accuracy is required. A GPS receiver with SBAS augmentation is sufficient.\n* Any DroneID error reported by the `/system/state` endpoint must cause an audiovisual indicator to signal a Remote ID failure to the operator.\n\nPlease refer to FAA 14 CFR Part 89, ASTM F3411 and ASTM F3586 for details.\n\n**Possible values:**\n\n* `US_REMOTE_ID_STANDARD`\n* `unset`\n\nIf unset, this operator is not considered as a UAS operator, and a RemoteID error might occur if regulation requires an operator but no other operator is present.\n\nIf no location information is provided, it is assumed that the operator is in direct vincinity of the Ground Station and the Ground Station location is used as the operator location.\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"}}}},"responses":{"WrongInput":{"description":"Request parameter doesn't meet criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/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"},"400":{"$ref":"#/components/responses/WrongInput"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Release control

> Releases control of the Fotokite system, allowing other clients (Fotokite Live, Fotokite API, or Plugin) to take control.<br>

```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":["control"]}],"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/v1/auth/token/request","scopes":{"read":"Grants access to retrieve system data and information.","control":"Allows sending commands to control the system.","can_override":"Allows to make `handoff/control/override` call to override current controlling client.","experimental":"Enables access to experimental API features.","internal":"Fotokite-internal functions. Not for third-party use."}}}}},"responses":{"InternalError":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"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":{"/v1/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":"Command was released successfully or requesting client successfully removed from the waiting queue or no one was controlling.\n"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## 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.<br>

```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":["control","can_override"]}],"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/v1/auth/token/request","scopes":{"read":"Grants access to retrieve system data and information.","control":"Allows sending commands to control the system.","can_override":"Allows to make `handoff/control/override` call to override current controlling client.","experimental":"Enables access to experimental API features.","internal":"Fotokite-internal functions. Not for third-party use."}}}}},"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"},"regulatory_mode":{"$ref":"#/components/schemas/OperatorRegulatoryMode"},"operator_gps_lat":{"description":"Latitude of the operator reported by GPS [-90..+90] (degrees)","type":"number","minimum":-90,"exclusiveMinimum":true,"maximum":90},"operator_gps_lon":{"description":"Longitude of the operator reported by GPS (-180..+180] (degrees)","type":"number","minimum":-180,"exclusiveMinimum":true,"maximum":180},"operator_gps_elevation":{"description":"Elevation of the operator reported by GPS (meters)","type":"number"},"operator_gps_accuracy":{"description":"Operator GPS accuracy in meters","type":"number","minimum":0}}},"OperatorRegulatoryMode":{"type":"string","description":"DroneID regulation variant that the UI provided to the operator complies with.\n\nDroneID broadcasts such as those required for FAA RemoteID contain information about the UAS operator. This endpoint can be used to provide such information. An update must be provided regularly according to the applicable regulation to prevent entering a DroneID error state (this may require sending handoff requests more frequently than it is required normally).\n\nBy setting this value, you declare compliance with the relevant regulation.\n\nFor the US:\n*  An operator location of sufficient accuracy is required. A GPS receiver with SBAS augmentation is sufficient.\n* Any DroneID error reported by the `/system/state` endpoint must cause an audiovisual indicator to signal a Remote ID failure to the operator.\n\nPlease refer to FAA 14 CFR Part 89, ASTM F3411 and ASTM F3586 for details.\n\n**Possible values:**\n\n* `US_REMOTE_ID_STANDARD`\n* `unset`\n\nIf unset, this operator is not considered as a UAS operator, and a RemoteID error might occur if regulation requires an operator but no other operator is present.\n\nIf no location information is provided, it is assumed that the operator is in direct vincinity of the Ground Station and the Ground Station location is used as the operator location.\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"}}}},"responses":{"InternalError":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/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"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.fotokite.com/fotokite-api/handoff.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.