Don’t have the resources or expertise to build out an API dashboard for your drone program from scratch?
Skyward offers pre-built reporting dashboards in PowerBI for insights into your drone program. Please contact Customer Success at firstname.lastname@example.org for more information and assistance.
Welcome to the externally accessible API for Skyward Enterprise customers. This document is designed to help you become familiar with the basic concepts of the Skyward API and includes code, call, and responses examples to get you started.
The Skyward API is a REST API, specifically JSON over HTTP.
Skyward's externally accessible API is available for customers with Enterprise subscriptions. Please contact Skyward's Customer Success Team at email@example.com for more information on subscribing or upgrading your account.
The main sources of documentation for Skyward APIs are:
- The explanation of basic concepts in this document
- Code, call, and responses examples included below
- The online OpenAPI reference documentation of all endpoints, which will be made available to Skyward Enterprise subscribers. This documentation is made using the OpenAPI specification (also known as Swagger). It allows you to interactively try out endpoints.
- Be advised that the online OpenAPI reference documentation lets you try out endpoints against our real, live production environment. If you do not wish to make changes to the production data of your organization, please contact Customer Success for assistance in advance.
The Skyward APIs consume and produce JSON payloads over an HTTPS connection. However, some requests may also require no payload and produce no payload.
- A valid base URL is required for all endpoints (in this document referred to as
- An endpoint is identified by its request path ("
- Often one or more request parameters are included in the request path ("
- Additional properties may further change the request, such as query parameters ("
?owningOrgUuid=...&status=...") and HTTP headers ("
- Many of the concepts in our system are uniquely identified within our system by UUIDS in their canonical textual representation (e.g.
In general, the Skyward API is modeled around core business concepts in our system, such as:
For each of these concepts, Skyward APIs may offer a number of endpoints using different HTTP verbs, such as:
DELETE: mark items as deleted, typically one per request
GET: get items; you would typically see different endpoints for getting a single item, or for multiple items
PATCH: partially update an item, based on instructions in the payload
POST: create a new item, to the image of the payload
PUT: fully update an item, to the image of the payload
Unless explicitly documented otherwise, payloads will be JSON, specifically JSON objects (preferred) or JSON arrays. This means that a payload will not be a primitive value like a string, number, boolean.
Response payloads are designed to be simple and discrete. Whether the response payload is a single item or multiple items, they are all of a single type, describing a simple core business concept.
While responses may include references (UUIDs) to items of other types, details for other items are not included in the main response payload. This makes for simple endpoints that return small payloads.
If the response payload of a request can contain multiple items, these items can be found as an array under the
content key. Additional keys are included with information about the list of responses. The following keys are supported:
content: array of multiple items
first: whether the current page is the first one
included: see the paragraph "Additional Includes"
last: whether the current page is the last one
number: the number of the current page
numberOfElements: the number of elements currently on this page
size: the size of the page
sort: the sorting parameters for the page
totalElements: the total amount of elements
totalPages: the number of total pages
If the response payload of a request can contain multiple items, these items will always be paginated. Only a single page is returned per request. A specific, 0-based page number can be requested using the
page query parameter. A desired page size can be requested using the
pageSize query parameter, and must be at least 1, and at most 100. If you want more than 100 items (i.e. if you want all items), it will be necessary to request multiple, consecutive pages. The default page is 0 (the first page). The default page size is 50.
Sometimes an additional item of another type in addition to the main response payload is desired. For example, you want to know the name of an organization UUID that is referenced in a response payload, or the operation to which the flight in a response payload belongs. For this, additional items can be included. Additional items can be included by requesting them using respective
@@include query parameters, as described in Skyward's OpenAPI reference documentation of endpoints. The original, main response payload can be found under the
content key, while the additional items can be found under the
included key. For example, if
personUuids are found in the main response payload, more details of these persons can be requested using the
@@include=person query parameter, and the respective persons are included under the
included.person key, like so:
The result of a request is indicated with an HTTP status code. Some interpretations of common status codes:
- HTTP 2xx: the request was successfully completed
- HTTP 400 Bad Request: some request parameter was invalid
- HTTP 401 Unauthorized: you could not be authenticated, because your access token is invalid or missing
- HTTP 403 Forbidden: you could not be successfully authorized to perform the request, for example because you are not a member of the organization, you don't have the appropriate roles, or you need to refresh your access token for the organization in the request
- HTTP 404 Not Found: the requested item could not be found; this status code is only used when the item that is the main subject of the request could not be found; if some related, required item could not be found rather a HTTP 400 Bad Request is the result
- HTTP 409 Conflict: due to an illegal state the request could not be successfully performed; a typical example is that an item could not be created because it already exists
- HTTP 429 Too Many Requests
- HTTP 5xx: something is wrong at the Skyward API; operations staff at Skyward will be notified whenever this happens, or you may contact the Customer Success team of Skyward for more information
For unsuccessful results, the response payload is mostly standardized, and has the following properties:
error: reason phrase of the HTTP status
exception: type name of the programmatic exception that was involved
message: brief hint or explanation why the request was unsuccessful
path: request path
status: code of the HTTP status (number)
timestamp: date/time of the response
Dates are formatted either as:
- ISO 8601 combined date and time representation, e.g. "
2019-02-19T00:28:21.646Z". Note that here the milliseconds are not optional
- Milliseconds since Unix epoch
Items are generally identified by strings that contain unique identifiers, looking something like "
Two types of authentication principals are supported:
- Person: a human user; or an
- Enterprise: an organization, typically some centralized process of the organization that it represents
Authentication follows a two-step approach:
- Exchange credentials for an access token
- Use the access token on requests to the other endpoints of the Skyward API
Credentials can never be used directly on other endpoints of the Skyward API.
Credentials of a human user are the same as they use for login to the Skyward user interface. A human user can submit their user name and password in exchange for an access token and a refresh token.
Online OpenAPI reference documentation about the credentials exchange for a human user can be found at
BASEURL is the provided URL to the Skyward API, and
PASSWORD are the same credentials as for login to the Skyward user interface.
Access tokens are associated with specific organizations. When making requests related to a specific organization, that organization must be included in the access token. (Although, for some requests it suffices to include an organization in the access token that is a parent in the enterprise organization hierarchy of the specific organization that the request relates to.)Specific organizations can be explicitly included while exchanging the credentials by including the organizationUuid query parameter. The user must have existing access to the requested organizations. To log into a different organization, the access token also needs to be refreshed, while specifying the requested, different organizations to log into.Most commonly, the access token includes a single access token, but an access token can be requested to include multiple organizations by repeatedly including the organizationUuid query parameter.If no organization is explicitly requested, the last used organization is included in the access token. This can be confusing and it is recommended that client code be explicit about organizations to include in the access token.
Credentials of an enterprise principal must be supplied explicitly by the Skyward Customer Success team. These credentials are not the same as those one used to login to the Skyward user interface. An enterprise principal can submit its login name/user name and password in exchange for an access token.
Online OpenAPI reference documentation about the credentials exchange for an enterprise principal can be found at
BASEURL is the provided URL to the Skyward API, and
PASSWORD are the credentials as explicitly supplied for your organization, by the Customer Success team of Skyward, for usage with the Skyward API.
The response from the credentials exchange looks as follows:
accessToken is used for requests to other API endpoints. The
refreshToken is used for obtaining a new access token.
Using an Access Token
Access tokens can be used on other API endpoints by including an HTTP header as follows:
Refresh Access Token
The access token gives access to other API endpoints, and has a relatively short expiration time. The refresh token has a relatively long expiration time. The expiration times are included when any new tokens are returned. The human user can submit the refresh token in exchange for a new access token and a new refresh token. They should do so just before a token is about to expire, or when the access token is already expired. If the refresh token is expired, they should start over and submit their user name and password for new tokens.
Example of refreshing the access token for a human user:
BASEURL is the provided URL to the Skyward API, and
REFRESHTOKEN is the refresh token that you obtained from an earlier credentials exchange or refresh.
For a human user, the specific organization(s) can be explicitly included for a refresh by including the organizationUuid query parameter. This does not need to be the same organization as on any earlier credentials exchange or refresh. The user must have existing access to the requested organization. For more about access to organizations, see the paragraph about credentials exchange (above).
The response from the refresh looks the same as the response from the credentials exchange.
Summary of several common authentication scenarios:
Retrieve an access token:
- Offer credentials to authentication endpoint (optionally specify the requested organization)
- An access token and a refresh token are returned
Get access to a specific endpoint of the Skyward API:
- Offer access token as authorization header on the request:
- The endpoint performs the request
Refresh an (expired) access token:
- Offer refresh token to authentication endpoint (optionally specify the requested organization)
- A new access token and a new refresh token are returned
Refresh an (expired) refresh token:
- Go back to "Retrieve an access token"
Get access to a service of a different organization:
- Go back to "Refresh an access token", specify the requested organization
Skyward is continuously improving our APIs. Non-breaking changes are released into the existing APIs at an ongoing basis. This means that any client code should remain compatible with these updates to the Skyward APIs. If there is any breaking changes to an API endpoint, a new major version is introduced. Major versions of API endpoints are identified by the first segment in the request path:
/api3 (V3), et cetera. Versioning is per endpoint, there is not an overall version of the Skyward API.
In accordance with your user agreement, your application must be a well-behaved user of Skyward APIs. In the case of excessive usage, requests may be throttled. Throttling may happen on specific endpoints, or for all requests of the same authorized principal. Throttling manifests by the Skyward API responding with a 429 status code ("Too Many Requests").
Client code should be resilient against throttling. You are recommended to implement a strategy of retries combined with progressive back-offs (for example exponential).
Specific attention is asked for authentication. You should reuse access tokens and refresh these using a refresh token. Please do not authenticate with your credentials, to request an access token for single use, for/before every request.
Please contact Customer Success at firstname.lastname@example.org for more information and assistance in your use of Skyward APIs.