SUPPORT CENTER

This article covers CloudAhoy's Organization Flights API.

Accessing the Organization flights endpoint

The /org/flights endpoint is available at

https://www.cloudahoy.com/integration/v1/org/flights

All requests to OAuth-secured endpoints must include an Authorization header, which provides the access token on behalf of which the request is being made:

Authorization: Bearer <org access token>

Importing a Flight

Executing an HTTP POST on the organization flights endpoint, providing the appropriate access token and a CloudAhoy formatted CSV file (or another CloudAhoy-supported file type, such as KML, GPX, or G1000 CSV) will import the flight into the account of a member of the organization.

When uploading a CloudAhoy formatted CSV file, the entire flight’s data can be uploaded in one file, or the upload can be incremental. For example, a 12-hours flight can be split into 4 files, 3 hours in each. All the files must have the same identical metadata.

Files of any other type must include the entire flight in a single file.

POST requests to the /org/flights endpoint require the org:flights:import OAuth scope

Specifying Account

The organization OAuth token with scope org:flights:import provides the ability to import into the account of any user or tail that is a member of the organization for which the token was issued.

Storing by User

Most organizational accounts are set up to store flight data in a user’s account.

In order to determine the specific account into which the flight should be imported, the email address corresponding to the account into which the flight will be imported must be specified.

If importing a CloudAhoy-formatted CSV file, the CSV file must specify the email field in the CSV file.

If importing any other supported filetype, the METADATA form field of the POST must specify the owner field (see the Form fields section below).

Storing by Tail

For organizations set to store flight data by a Tail Number, the flight’s metadata can omit an owner field and instead include only a tail field.

The METADATA form field of the POST must specify the tail field (see the Form fields section below).

Including an owner will cause the flight to also show up in the flights tab for the specified email.

Form Fields

The file to import must be specified by the IMPORT form field of the post.

A JSON-formatted string containing metadata about the flight must be specified by the METADATA form field of the POST. The properties of the metadata are described in the following table:

Metadata Object

For example, the following shell command uses curl to import the file /tmp/my_flight.csv:

$ curl -F "IMPORT=@/tmp/my_flight.csv" \
       -F 'METADATA={"importerVersion":"v1.23.4"}' \
       -H "Authorization: Bearer <org access token>" \
        https://www.cloudahoy.com/integration/v1/org/flights

Here’s another example, importing the file /tmp/g1000.csv and specifying the owner and other parameters via the METADATA form field of the POST.

curl -F "IMPORT=@/tmp/g1000.csv" \
     -F 'METADATA={"importerVersion":"v1.23.4",
            "owner":{"name":"maverick@topgun.mil", "role":"Student"},
            "other":{"name":"viper@topgun.mil", "role":"Instructor"},
            "aircraft_make":"GRUMMAN", 
            "aircraft_model":"F-14",
            "isSim": 1}' \
       -H "Authorization: Bearer <org access token>" \
        https://www.cloudahoy.com/integration/v1/org/flights

Return value

A successful import will result in the following return object:

The key returned may be used for a period of time to link directly to the flight:

http://www.cloudahoy.com/debrief/?key=<imported flight key>

Be aware that the import can be successful, but the flight can not be debriefable. This may occur if no airborne segments are detected in the flight or if there are too few data samples. In these cases, the error property will be present and populated in the object returned by the import.

If the request or file is malformed, an HTTP status 400 will be returned, with a text description of the problem.