Getting started
Get API access
The Fotokite API must be enabled by Fotokite. Please contact us to have your Fotokite system enrolled.
Access the API
Update the Fotokite system to the latest software version.
Choose one of the following network setups and follow the linked instructions:
Standalone setup Connect your client device directly to the Ground Station. Select Standalone setup
Integrated setup Connect both the Ground Station and your client device to the same local network. Select Integrated setup
Once the network setup is complete, you can access the API.
# HTTP (Standalone setup)
curl http://192.168.2.100:3128/api/v1/health
# HTTPS (Integrated setup)
curl https://<fotokite-system-name>.sigma.fotokite-system.com/api/v1/healthThe /health endpoint does not require authentication. For all other endpoints, use authenticated requests as described in Authentication.
For simplicity, this guide uses the URL for the Standalone setup. If you are using the Integrated setup, replace the URL accordingly.
If the command hangs, times out, or returns a “no route to host” error, your client device is not correctly connected to the Fotokite system.
Authentication
The authentication mechanism ensures proper security and access control. Most API endpoints are protected and scoped, meaning each request to a protected endpoint must include a valid bearer token. The Fotokite API offers two authentication mechanism:
Get a token via Token Management
Get a token via API Key
You can find more details in Authentication and Security
Get a token via Token Management
The simplest way to obtain a token is through our Token Management system. This method is recommended if you manage fewer than five systems.
Connect a computer with a web browser to the same network as your Fotokite system. We recommend using Wi-Fi.
Open the following URL in your browser.
http://192.168.2.100:3128/api/token_management
Click the Create API token button to create a new token.
Name: The name will help you organize your tokens. It will also be visible in Fotokite Live whenever your app uses that token to perform any controls.
Scope: Token scopes determine which endpoint(s) an API token can access.
read: Access to all endpoints for retrieving information, except
/controlendpoints.control: Access to
/controlendpoints.experimental: Access to experimental and unstable features.
The token (bearer token) is used to authenticate all subsequent requests to protected endpoints.
# System information
curl -X GET "http://192.168.2.100:3128/api/v1/system/info" \
--oauth2-bearer <auth_token>Tokens can be invalidated via Authentication. Once a token is invalidated, you must request a new one using Token Management.
Good to know: This token does not expire.
Retrieve system information
Basic information about the system, flight, camera, and other components can be retrieved using the endpoints in the /info namespace:
Control the system
To control the system, you must use the endpoints in the /control namespace. It is important to note that these endpoints are part of the Control Handoff mechanism. Control Handoff ensures that only one client can control the system at any given time. Before using any endpoint in the /control namespace, the application must first request control.
To keep the API in control, request control has to be sent in regular intervals by the client. Please find more details in Handoff.
If Fotokite Live is currently in control when the API requests control, an alert will be displayed to the operator. The operator can choose to allow or cancel the request. If the request is canceled, no additional alerts will appear for the next two minutes.
Fotokite Live can always take control back from the API by pressing the Take Control button in the bottom-right corner.
Retrieve system information via WebSockets
The API can notify your application about changes using WebSockets. You can subscribe to most endpoints by appending /subscribe to the endpoint URL when using the WebSocket protocol. In general, endpoints in the /state namespace are intended to be subscribed to via WebSockets.
The API sends updated information over WebSockets as soon as it becomes available. The data is delivered as a sequence of WebSocket binary messages, each containing a JSON object in the same format returned by the corresponding endpoint.
Accessing video streams
Video streams are available as H.264-encoded RTSP sources, which can be accessed using any RTSP client (eg. VLC media player). Learn more in Local Video Streaming (RTSP). The video streams are available only while the Kite is flying.
To retrieve information such as the ID, protocol, frame width, frame height, codec, and URLs for the video streams, use:
With the info provided via the API you can start consuming the RTSP video. For low-latcency streaming, we recommend e.g. using GStreamer with a pipeline configured as follows:
Code examples can be found in Video Streams.
Subscribe to system notifications
To monitor the state of the system, especially during flight, it is strongly recommended to subscribe to system notifications via webSockets. More details can be found in Notifications.
An overview of important notifications can be found in the Fotokite Sigma User Manual under https://manual.fotokite.com/failure-modes/messages-and-warnings
Remote ID
For drones with Remote ID (USA) enabled, API endpoints such as Take off require an operator to be present.
This requirement can now be fulfilled in two ways:
By connecting a Fotokite tablet, or
By providing operator and regulatory information via Handoff
If neither is available, the system will block takeoff. The state of Remote ID can be monitored using the relevant system endpoints (e.g. /system/state).
More details can be found in https://manual.fotokite.com/operational-guidelines/faa-remote-id-usa.
Errors
API calls that are not understood by the system or that cannot be processed are signaled using standard HTTP status code. Conditions that affect the operation of the overall system (such as inability to take off) are generally not reported using HTTP status codes. Instead, the problem will be reported asynchronously as a notification, while the original API request succeeds.
200
OK (queries)
201, 202
Command accepted/queued
400
Bad Request, typically malformed request body or parameter values outside the permissible range
401
Authentication required. Provide an access token.
403
Authenticated, but the session can't perform this operation right now, e.g. due to another client controlling the system.
404
Invalid endpoint name or resource/component not present in the system.
405
Method not allowed, specifically includes attempts to subscribe a Websocket connection to an endpoint that does not support subscription.
409
Invalid state, the operation can't be performed in the current operating state (e.g. rotation while the Kite is not flying).
429
Rate limited, all requests are subject to strict rate limits to ensure the reliability of the API service when interacting with misconfigured clients. In case of a 429 error, back off (0.1s-1s) and retry. Authentication failures (401) can cause more strict rate limiting, back off for 10s to reset all rate limits.
503
The operation can't be performed right now due to the system not being fully initialized yet, retry later.
Most errors come with a standard JSON body that contains an error code and an error message. The error code uniquely identifies the error condition and can be used by Fotokite support to pinpoint the precise issue. The error message is provided for developers' convenience and explains what caused the error. Clients must not rely on error codes or messages to function; only the HTTP status codes are guaranteed to be stable between releases. Error messages should not be displayed to operators, they are only targeted at developers.
Any problems that should be reported to operators are presented as notifications, and can be localized using the notifications dictionary.
Last updated