> 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/getting-started.md).
# Getting started
## Get API access
The Fotokite API must be enabled by Fotokite. Please contact us to have your Fotokite system enrolled.
Contact Fotokite
## Access the API
{% stepper %}
{% step %}
Update the Fotokite system to the latest software version.
{% endstep %}
{% step %}
Choose one of the following network setups and follow the linked instructions:
* **Standalone setup**\
Connect your client device directly to the Ground Station. \
Select [Network Integration](/network-integration.md#standalone-setup)
* **Integrated setup**\
Connect both the Ground Station and your client device to the same local network. \
Select [Network Integration](/network-integration.md#integrated-setup)
{% endstep %}
{% step %}
Once the network setup is complete, you can access the API.
```bash
# HTTP (Standalone setup)
curl http://192.168.2.100:3128/api/v1/health
# HTTPS (Integrated setup)
curl https://.sigma.fotokite-system.com/api/v1/health
```
The `/health` endpoint does not require authentication. For all other endpoints, use authenticated requests as described in [#authentication](#authentication "mention").
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.
{% endstep %}
{% endstepper %}
## 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 Autencation mechanism:
1. Get a token via Token Management
2. Get a token via API Key
You can find more details in [Authentication and Security](/authentication-and-security.md)
### 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.
{% stepper %}
{% step %}
Connect a computer with a web browser to the same network as your Fotokite system. We recommend using Wi-Fi.
{% endstep %}
{% step %}
Open the following URL in your browser.
```bash
http://192.168.2.100:3128/api/token_management
```
{% endstep %}
{% step %}
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 `/control` endpoints.
* control: Access to `/control` endpoints.
* experimental: Access to experimental and unstable features.
{% endstep %}
{% step %}
The token (bearer token) is used to authenticate all subsequent requests to protected endpoints.
```bash
# System information
curl -X GET "http://192.168.2.100:3128/api/v1/system/info" \
--oauth2-bearer
```
{% endstep %}
{% step %}
Tokens can be invalidated via [Authentication](/fotokite-api/authentication.md#post-v0-auth-token-invalidate). Once a token is invalidated, you must request a new one using Token Management.
Good to know: This token does not expire.
{% endstep %}
{% endstepper %}
## Retrieve system information
Basic information about the system, flight, camera, and other components can be retrieved using the endpoints in the `/info` namespace:
```bash
# System information
curl -X GET "http://192.168.2.100:3128/api/v1/system/info" \
--oauth2-bearer
# Flight information
curl -X GET "http://192.168.2.100:3128/api/v1/flight/info" \
--oauth2-bearer
# Camera information
curl -X GET "http://192.168.2.100:3128/api/v1/camera/info" \
--oauth2-bearer
```
## 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](/fotokite-api/handoff.md#post-v0-handoff-control-request).
{% code fullWidth="false" %}
```bash
# Request control
curl -X POST "http://192.168.2.100:3128/api/v1/handoff/control/request" \
-H "Authorization: Bearer "
-H "Content-Type: application/json" \
-d '{"operator_name":"YOUR_OPERATOR_NAME"}'
# Take off
curl -X POST "http://192.168.2.100:3128/api/v1/flight/control/take_off" \
-H "Authorization: Bearer "
# Set Altitude
curl -X POST "http://192.168.2.100:3128/api/v1/flight/control/set_altitude" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"altitude":21}'
# Land
curl -X POST "http://192.168.2.100:3128/api/v1/flight/control/land" \
-H "Authorization: Bearer "
# Release control
curl -X POST "http://192.168.2.100:3128/api/v1/handoff/control/request" \
-H "Authorization: Bearer "
```
{% endcode %}
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.
In Fotokite Live, control is blocked when the API has control.
## 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.
```bash
# Flight state
websocat -H="Authorization: Bearer " \
ws://192.168.2.100:3128/api/v1/flight/state/subscribe
# Camera state
websocat -H="Authorization: Bearer " \
ws://192.168.2.100:3128/api/v1/camera/state/subscribe
```
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](https://www.videolan.org/vlc/)). Learn more in [Local Video Streaming (RTSP)](https://manual.fotokite.com/installation-and-integration/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:
```bash
# Video streams
curl -X GET "http://192.168.2.100:3128/api/v1/videostreams" \
--oauth2-bearer
```
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:
```bash
// GStreamer
gst-launch-1.0 rtspsrc location=rtsp://192.168.2.100:554/zoom drop-on-latency=true latency=300 ! rtph264depay ! h264parse ! avdec_h264 ! queue ! xvimagesink
```
Code examples can be found in [Video Streams](/code-examples/video-streams.md).
## 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](/fotokite-api/notifications.md).
```bash
# Notifiactions
websocat -H="Authorization: Bearer " \
ws://192.168.2.100:3128/api/v1/notifications/state
```
An overview of important notifications can be found in the Fotokite Sigma User Manual under
## 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](/fotokite-api/handoff.md#post-v0-handoff-control-request)
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 .
## 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.
| HTTP Status Code | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 | OK (queries) |
| 201, 202 | Command accepted/queued |
| 400 | Bad Request, typically malformed request bod y 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.
---
# 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/getting-started.md?ask=&goal=
```
`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.