REST API Documentation

    About
    Examples Request Structure Entitlements Authentification
    Requests
    Application Requests Device Requests Metrics Requests User Requests Report Requests Service Requests Gateway Requests
    Async Metrics Schema
    Models
    Enums Models Properties Data Types

    About

    Examples

    All of the example requests are written using curl with bash. The variables service and user are expected to be set. Any Guid's referenced need to be substituted for locally applicable IDs.

    Example of setting the environment variables:

    export [email protected]:bca2e6ae-d0c2-4833-9fcd-9446076442a5 export service=http://10.10.0.30

    Request Structure

    Requests are composed of several components. The URL is structured as protocol://address:port/path?query. POST requests can optionally contain data that is not part of the URL, GET requests can not. The protocol will be http or https depending on your services configuration. The address:port is identical to the one configured for use with GigaFox's web service. The path is always one or more static nouns. Dynamic nouns, such as IDs, and verbs, are in the query. GigaFox's REST API is structured that all requests getting data use GET requests. All requests to modify data use POST requests and return a ResultModel.

    Entitlements

    Each user is assigned roles with varying degrees of entitlements, allowing users access to certain features, functions, and actions. Once roles are assigned, users will only have access to the entitlements determined by assigned role(s). A full list of entitlements can be found in the Users section of the GigaFox user guide.

    Authentification

    Authentication is performed using BASIC http authentication with the user's API token as the password.

    Requests

    Application Requests

    GET /Application

    Fetch the list of applications stored in GigaFox.

    Entitlement: Application list
    Query: Optional Application query properties filter
    Result: Application[]

    Examples:

    Fetch the complete list of applications:
    curl -u $user "$service/apiv1/Application"

    Fetch only the application with the ID 477f5020-fe89-4675-8e6d-92ed4302105a:
    curl -u $user "$service/apiv1/Application?id=477f5020-fe89-4675-8e6d-92ed4302105a"

    POST /Application?update&id={Guid}

    Update the stored application.

    Entitlement: Application modify
    Result: ResultModel

    Query:
    Field Type Description
    id application GUID The ID of the application to update.
    Data:
    Field Type Description
    Application update properties update A JSON object of the properties to change and their new values.

    Examples:

    Update the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a DisplayName property to be "New application name":
    curl -XPOST -u $user "$service/apiv1/Application?update&id=477f5020-fe89-4675-8e6d-92ed4302105a" \ -H "Content-Type: application/json" \ -d "{DisplayName:\"New application name\"}"

    POST /Application?delete&id={Guid}

    Delete an application so that it is no longer stored by GigaFox.

    Entitlement: Application delete
    Result: ResultModel

    Query:
    Field Type Description
    id application GUID The ID of the application to delete.
    all bool? If set to true, all applications with the same identifier are deleted. If set to false or excluded, only the application specified by id is deleted.

    Examples:

    Delete the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a:
    curl -XPOST -u $user "$service/apiv1/Application?delete&id=477f5020-fe89-4675-8e6d-92ed4302105a"

    POST /Application?add

    Upload an application to be stored by GigaFox.

    Entitlement: Application upload
    Query: None
    Data: The application binary.
    Result: AsyncResponse<Application>

    Examples:

    Upload the file "C:\files\deviceControl.ipa" as an application:
    curl -XPOST -u $user "$service/apiv1/Application?add" --form "upload=@C:\files\deviceControl.ipa"

    POST /Application?action=install&id={Guid}&deviceId={string}

    Install a GigaFox stored application to a device.

    Entitlement: Device application management
    Result: AsyncResponse<ResultModel>

    Query:
    Field Type Description
    id application GUID The ID of the application to install.
    deviceId GigaFox ID, serial number, or vendor ID The device to install the application to.
    force bool? If set to true, any existing copy of the application is uninstalled and all user data for it is deleted. This may be required when changing signing certificates on iOS or Android. If false or excluded, a normal application installation is attempted.
    nativeAutomation bool? If set to true, the application is installed ready for using native automation with Trust automation. If false or excluded, the application is installed normally.

    Examples:

    Install the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a to the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Application?action=install&id=477f5020-fe89-4675-8e6d-92ed4302105a&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Application?action=uninstall&id={Guid}&deviceId={string}

    Uninstall a GigaFox stored application from a given device.

    Entitlement: Device application management
    Result: ResultModel

    Query:
    Field Type Description
    id application GUID The ID of the application to uninstall.
    deviceId GigaFox ID, serial number, or vendor ID The device to uninstall the application from.
    removedata bool? If set to true or excluded, the user data for the application is removed. If set to false, the application data is preserved. This would be any files that the application has stored.

    Examples:

    Uninstall the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a from the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Application?action=uninstall&id=477f5020-fe89-4675-8e6d-92ed4302105a&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Application?action=uninstallBundle&bundleId={string}&deviceId={string}

    Uninstall an application by bundle ID from a given device.

    Entitlement: Device application management
    Result: ResultModel

    Query:
    Field Type Description
    bundleId string The bundle id of the application to uninstall.
    deviceId GigaFox ID, serial number, or vendor ID The device to uninstall the application from.
    removedata bool? If set to true or excluded, the user data for the application is removed. If set to false, the application data is preserved. This would be any files that the application has stored.

    Examples:

    Uninstall the application with bundle ID com.mobilelabs.trustbrowser from the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Application?action=uninstallBundle&bundleId=com.mobilelabs.trustbrowser&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Application?action=launch&id={Guid}&deviceId={string}

    Launch an application that is installed on a device.

    Entitlement: Device connect
    Result: AsyncResponse

    Query:
    Field Type Description
    id application GUID The ID of the application to launch.
    deviceId GigaFox ID, serial number, or vendor ID The device to launch the application on.
    startOnly bool? If set to true, no instrumentation is performed on the application.
    arguments string The arguments to send to "am start" on Android, or the arguments to pass to the program on iOS.

    Examples:

    Launch the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a on the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Application?action=launch&id=477f5020-fe89-4675-8e6d-92ed4302105a&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    Application GUID:
    The application GUID is located in the URL of the applications details page.

    Device Requests

    GET /Device

    Fetch the list of devices managed by GigaFox.

    Entitlement: Device list
    Query: Optional Device query properties filter
    Result: Device[]
    Notes: The Properties field is not included by default to reduce the amount of data per request. When properties is set, the results of getprop for Android devices and a flattened structure of the lockdownd properties for iOS devices.
    Notes: applications is only available when "applications" flag is set.

    Query:
    Field Type Description
    properties bool? Include the Properties field.
    applications bool? If set to true, returns the GigaFox managed applications that are installed on the device in installedApplications.
    allApplications bool? If set to true, returns all applications that are installed on the device in installedApplications. Applications not managed by GigaFox will have 00000000-0000-0000-0000-000000000000 as their id.

    Examples:

    Fetch the complete list of devices:
    curl -u $user "$service/apiv1/Device"

    Fetch only the devices that are online, including the device's properties list in the results:
    curl -u $user "$service/apiv1/Device?availability=Online&properties=true"

    Fetch only the devices that are enabled and online:
    curl -u $user "$service/apiv1/Device?enabled=true&availability=Online"

    Fetch the device and application properties for the device with ID 0a7c9243-dj18-44cd-919a-nnd31hhf624:
    curl -u $user "$service/apiv1/Device?applications=true&id=0a7c9243-dj18-44cd-919a-nnd31hhf624f&"

    Fetch a complete list of devices, including installed application data:
    curl -u $user "$service/apiv1/Device?applications=true&"

    GET /Device/Available

    Fetch a list of devices with an Available status that the user can retain. The output will not include devices with a Retained/In-Use, Disabled, or Reserved (by another user) status.

    Entitlement: Device list
    Result: Device[]
    Notes: The Properties field is not included by default to reduce the amount of data per request. When properties is set, the results of getprop for Android devices and a flattened structure of the lockdownd properties for iOS devices.
    Notes: applications is only available when "applications" flag is set.

    Query:
    Field Type Description
    properties bool? Include the Properties field.
    applications bool? If set to true, returns the GigaFox managed applications that are installed on the device in installedApplications.
    allApplications bool? If set to true, returns all applications that are installed on the device in installedApplications. Applications not managed by GigaFox will have 00000000-0000-0000-0000-000000000000 as their id.

    Examples:

    Fetch a list of devices with an Available status:
    curl -u $user "http://$server/apiv1/Device/Available"

    GET /Device/Log?id={string}

    Fetch the device's system log.

    Entitlement: Device list
    Result: string.

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The device to get the system log for.

    Examples:

    Fetch the system log for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -u $user "$service/apiv1/Device/Log?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    GET /Device/AppiumLog?id={string}

    Fetch the appium stdout/stderr output log.

    Entitlement: Device list
    Result: string.

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The device to get the system log for.
    currentSessionOnly bool? Only return logs for the current (or if session has ended, the last active) session.

    Examples:

    Fetch the Appium log for the current session for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -u $user "$service/apiv1/Device/AppiumLog?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&currentSessionOnly=true"

    POST /Device?delete&id={string}

    Delete a device that is no longer managed by GigaFox. This can only be done to offline devices.

    Entitlement: Device list, Device delete
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to delete.

    Examples:

    To delete device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?delete&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Device?update&id={string}

    Update the stored device model.

    Entitlement: Device list, Device modify
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to update.
    Data:
    Type Description
    Device update process A JSON object of the properties to change and their new values.

    Examples:

    Update the note field for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6 to say "This device is in-use by automation.":
    curl -XPOST -u $user "$service/apiv1/Device?update&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6" \ -H "Content-Type: application/json" \ -d "{Notes:\"This device is in-use by automation.\"}"

    POST /Device/UsbPort?update&id={string}&usbHubPortState={UsbHubPortState}

    Update the state of a USB hub port. This allows alternative a device's USB hub port between disconnect, charging, and data modes.

    Entitlement: Manage USB hubs
    Result: ResultModel

    , or *
    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor IDThe ID of the device to update. If * is specified, then all devices are targeted.
    usbHubPortState UsbHubPortState The state to transition the USB hub port to.

    Examples:

    Change the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6 usb hub port state to charging:
    curl -XPOST -u $user "$service/apiv1/Device/UsbPort?update&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&usbHubPortState=Charge"

    Change all devices usb hub port state to data:
    curl -XPOST -u $user "$service/apiv1/Device/UsbPort?update&id=*&usbHubPortState=Data"

    POST /Device?action=reboot&id={string}

    Reboot the operating system on the device. The device's availability will show Offline until the reboot has completed.

    Entitlement: Device reboot
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to reboot.

    Examples:

    Reboot the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?action=reboot&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Device?action=retain&id={string}

    Set a device as retained by the authenticated user inside GigaFox. This prevents other users from performing most actions on the device. See the GigaFox user's guide for more details.

    Entitlement: Device connect
    Result: ResultModel<DeviceAccessTicket>

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to retain.

    Examples:

    Retain the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?action=retain&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Device?action=release&id={string}

    Release the retain held on a device.

    Entitlement: If not the owner of retain, "Device release any"
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to release.

    Examples:

    Release the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?action=release&id=1c32079b-53bc-4-bc4-bcf6-71444a7e6bb6"

    POST /Device?action=enable&id={string}

    Enable a device to be managed by GigaFox. While a device is disabled, it can not be used but does not count toward the licensed device limit.

    Entitlement: Device enablement
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to enable.

    Examples:

    Enable the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?action=enable&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Device?action=disable&id={string}

    Disable a device so it is no longer accessible from GigaFox. While a device is disabled, it can not be used but does not count toward the licensed device limit.

    Entitlement: Device enablement
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to disable.

    Examples:

    Disable the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?action=disable&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    POST /Device?action=reset&id={string}

    Reset the state of a device. Resetting device state is to permit increased determinacy of the device's state between usage or testing sessions.

    Entitlement: If uninstallAll is enabled, "Device application management", if reboot is enabled, "Device reboot."
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to reset.
    uninstallAll bool? If set to true, all user installed applications on the device will be uninstalled. If false, no applications are uninstalled. If excluded, the default inside GigaFox's System area is used.
    reboot bool? If set to true, the device is reboot. If false, no reboot is performed. If excluded, the default inside GigaFox's System area is used.

    Examples:

    Reset the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device?action=reset&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    Metrics Requests

    GET /Device/Metrics?id={string}&table={string}

    Query the device metrics database for specified metrics for a given device.

    Entitlement: Device list
    Result file

    Metrics are gathered passively in the background for all devices managed by GigaFox, unless explicitly disabled. The metrics collected are to the best available for the given device which has some variance as documented. The metrics are stored in an InfluxDB service, which has some implications as documented.

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device to query metrics for.
    table string

    Tables to select fields from. Formatted as a comma delineated list of measurement names. Table names are listed in the metrics schema.

    Example: &table=event, &table=event,log

    Warning: Referencing more than one table in a single query has a severe performance impact in InfluxDB.
    fields string? A list of fields to select. If excluded, all fields from the referenced tables will be returned. Referencing specific fields can drastically decrease the response size. Formatted as a comma delineated list of fields. Field names are listed in the metrics schema.
    aggr string?

    A list of functions to perform on the referenced fields. When used, "fields" becomes a required argument. Formatted as a comma delineated list. Each function is implicitly given each listed field as the first argument. The function list is shown in influxdata.

    Example: Get the max aggregate of 2 fields. &aggr=max&fields=fieldA,fieldB performs the query as SELECT max(fieldA), max(fieldB)

    Example: Get the max aggregate and mean of 2 fields. &aggr=max,mean&fields=fieldA,fieldB performs the query as SELECT max(fieldA), max(fieldB), mean(fieldA), mean(fieldB)
    marker string? The name of a marker. When used, the results are limited to the intermediate periods for the most recent specified markers. The marker session is automatically inserted for the periods of time when a device is retained. Custom markers can be inserted using the startmarker and stopmarker API actions. When a marker is specified, start and end are ignored.
    Example: Get the metrics for the last 5 sessions.
    &marker=session&markerLimit=5
    markerLimit int? The number of number of marker entries to reference. If not specific, defaults to 1. Having a markerLimit greater than 1 produces multiple timelines in a single result and may not be directly processable. This is a side effect of InfluxDB.
    markerOffset int? The number of markers to skip. For example, if markerLimit is 1, and markerOffset is 3, then the 4th previous marker entry will be used.
    limit int? Limit the result rows to the specified limit. If not set, there is no limit. limit can be used with offset to "page" results in smaller portions. limit is required if marker, start, and end are not present.
    offset int? The result row to start at. Can only be specified if limit is also specified.
    start DateTime?
    end DateTim? The time range to limit the query to. Both do not need to be specified. These values are ignored if marker is present.
    groupBy string? A field name to group the results by.
    orderBy string? A field name to order the results by. Due to limitations in InfluxDB, at present only the time field is supported. An ordering direction can be specified after a space in the field name. Ascending is assumed, desc can be specified manually.
    Example: Order by time descending. &orderBy=time+desc
    format string? The format of the result. Possible values are csv and default. If CSV is not given, default is assumed. default is a pass-through of the JSON returned by InfluxDB. This permits any InfluxDB result processing tool to be used. Documentation of the format is available on their site: influxdata csv is a transcoding of the JSON to CSV format. CSV is beneficial in it may be less CPU intensive to process,could consume less bandwidth, and has compatibility with any CSV processing application.
    filename string? The filename for the returned document. If not specified, the default is "metrics-" followed by the device's name. The extension is automatically set according to the specified format.
    timeout int? The optional number of seconds to allow the query to run. The default is 120 seconds. This may need to be adjusted for more complex or larger queries.

    Examples:

    Get the mean CPU usage during for the last usage session for device ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -u $user "$service/apiv1/Device/Metrics?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&marker=session&aggr=mean&table=sample&fields=Load"

    Download all metrics from the sample table to a CSV file for the last usage session for device ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -OJ -u $user "$service/apiv1/Device/Metrics?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&marker=session&table=sample&format=csv"

    POST /Device/Metrics?action=startmarker&id={string}&name={string}

    Start a metrics marker. The marker must be ended using stopmarker. The marker's timespan is represented by when the startmarker and stopmarker calls were made. Markers are used as named reference points into the metrics timeline. Multiple calls to startmarker can be made before calling stopmarker given each call has a unique name.

    Entitlement: Device list
    Result: ResultModel

    Query:
    Field Type Description
    id GigaFox ID, serial number, or vendor ID The ID of the device.
    name string The name of the marker. There are no character limitations.

    Examples:

    Start a metrics marker by the name "account-login" for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device/Metrics?action=startmarker&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&name=account-login"

    POST /Device/Metrics?action=stopmarker&id={string}&name={string}

    End the metrics marker of the same name for the same device as passed to startmarker.

    Entitlement: Device list
    Result: ResultModel

    Query:
    Field Type Description
    id Guid GigaFox ID, serial number, or vendor ID
    name string The name of the marker which was passed to startmarker.

    Examples:

    Ends the metrics marker by the name "account-login" for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device/Metrics?action=stopmarker&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&name=account-login"

    The metrics for the last marker named "account-login" can now be queried like:
    curl -XPOST -u $user "$service/apiv1/Device/Metrics?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&table=sample&marker=account-login"

    POST /Device/Metrics?action=enabled&id={string}&enable={bool}

    Enable or disable passive metric logging for a device. By default, all devices have passive logging enabled. It's recommended that this be turned off if the performance overhead on the device is detrimental to testing.

    Entitlement: Device list, Device modify
    Result: ResultModel

    Query:
    Field Type Description
    id Guid GigaFox ID, serial number, or vendor ID
    enable bool Set to true if metrics should be passively logged for this device.

    Examples:

    Disable passive metrics monitoring for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -XPOST -u $user "$service/apiv1/Device/Metrics?action=enabled&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&enable=false"

    User Requests

    GET /User

    Fetch the list of GigaFox users.

    Entitlement: Without "User list", only the authenticated user is returned.
    Data: Optional User query properties filter.
    Result: User[]

    Examples:

    Fetch all users:
    curl -u $user "$service/apiv1/User"

    Fetch all users who have the postal code "90210":
    curl -u $user "$service/apiv1/User?PostalCode=90210"

    POST /User?update&id={Guid}

    Modify a specified user record.

    Entitlement: "User modify" to modify any user, "User modify self" to modify authenticated user.
    Result: ResultModel

    Query:
    Field Type Description
    id Guid The ID of the user.
    Data:
    Type Uses Description
    User update properties update A JSON object of the properties to change and their new values.

    Examples:

    Update the user with ID 571c211e-96d8-4dad-b11d-7e5e80e2c5fb first name to "John" and last name to "Doe":
    curl -XPOST -u $user "$service/apiv1/User?update&id=571c211e-96d8-4dad-b11d-7e5e80e2c5fb" \ -X POST -H "Content-Type: application/json" \ -d "{LastName:\"Doe\",FirstName:\"John\"}"

    POST /User?add

    Create a new GigaFox user.

    Entitlement: User import
    Result: ResultModel

    Data:
    Type Description
    User The model of the new user to create.

    Examples:

    Create a user with the username [email protected], the password correcthorsebatterystaple, and the name "John Doe":
    curl -XPOST -u $user "http://10.4.5.135/apiv1/User?add" \ -X POST -H "Content-Type: application/json" \ -d "{Email:\"[email protected]\",Password:\"correcthorsebatterystaple\",isActive:\"true\",LastName:\"Doe\",FirstName:\"John\"}"

    Report Requests

    GET /Report/Availability

    Fetch device availability and use history.

    Entitlement: User list, Device list, Application list

    Query:
    Field Type Description
    days int? Only events newer than this many days old are returned. Used instead of fromDate.
    fromDate DateTime? Only events newer than the provided date are returned. If excluded, there is no minimum date.
    toDate DateTime? Only events older than the provided date are returned. If excluded, there is no maximum date.
    window DateTime? Only events within the set period of time. A time period with 30 second intervals would be window=00:00:30.

    Examples:

    Fetch device availability every 30 seconds:
    curl -u $user "$service/apiv1/Report/Availability?window=00:00:30&"

    Fetch device availability stating from April 1, 2019:
    curl -u $user "$service/apiv1/Report/Availability?toDate=04-01-2019&"

    GET /Report/History

    Fetch an action history report.

    Entitlement: User list, Device list, Application list
    Result: EventHistory

    Query:
    Field Type Description
    applicationId Guid? Return only history for the application with this ID. If excluded, all applications are returned.
    deviceId GigaFox ID, serial number, or vendor ID Return only history for the specified device. If excluded, all devices are returned.
    userId Guid? Return only history for the user with this ID. If excluded, all users are returned.
    fromDate DateTime? Only events newer than the provided date are returned. If excluded, there is no minimum date.
    toDate DateTime? Only events older than the provided date are returned. If excluded, there is no maximum date.
    days int? Only events newer than this many days old are returned. Used instead of fromDate.
    skip int? The numeric starting entry to return the history from. Can be used in conjunction with take to paginate results.
    take int? The maximum number of entries to return. Can be used in conjunction with skip to paginate results.

    Examples:

    Get all events from the past 5 days performed by user with ID 571c211e-96d8-4dad-b11d-7e5e80e2c5fb:
    curl -u $user "$service/apiv1/Report/History?days=5&userId=571c211e-96d8-4dad-b11d-7e5e80e2c5fb"

    GET /Report/Usage

    Fetch a device usage history report.

    Entitlement: User list, Device list, Application list
    Result: DeviceUsageHistory

    Query:
    Field Type Description
    applicationId Guid? Return only history for the application with this ID. If excluded, all applications are returned.
    deviceId GigaFox ID, serial number, or vendor ID Return only history for the specified device. If excluded, all devices are returned.
    userId Guid? Return only history for the user with this ID. If excluded, all users are returned.
    fromDate DateTime? Only events newer than the provided date are returned. If excluded, there is no minimum date.
    toDate DateTime? Only events older than the provided date are returned. If excluded, there is no maximum date.
    days int? Only events newer than this many days old are returned. Used instead of fromDate.
    skip int? The numeric starting entry to return the history from. Can be used in conjunction with take to paginate results.
    take int? The maximum number of entries to return. Can be used in conjunction with skip to paginate results.

    Examples:

    Get all usage records from the past 7 days for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
    curl -u $user "$service/apiv1/Report/Usage?days=7&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

    Service Requests

    GET /Service

    Fetch GigaFox history service installation information.

    Entitlement: System configuration area access
    Result: HubInformation

    Examples:

    Fetch the results:
    curl -u $user "$service/apiv1/Service?"

    Gateway Requests

    GET /Gateway

    Fetch information about the attached device gateways and any associated USB hubs and their attached devices.

    Entitlement: View gateways
    Result: GatewayDescription[]

    Examples:

    Fetch the device gateway information:
    curl -u $user "$service/apiv1/Gateway"

    POST /Gateway/UsbHub?update&id={string}&usbHubPort={int}&usbHubPortState={UsbHubPortState}

    Change the port state to usbHubPort for the port number given as usbHubPort on the USB hub given as a serial number in id.

    Entitlement: Manage USB hubs
    Result: ResultModel

    Query:
    Field Type Description
    id string The serial number for the USB hub.
    usbHubPort int The numerical port number of the USB hub port to change.
    usbHubPortState UsbHubPortState The state to transition the port to.

    POST /Gateway/UsbHub?action=reboot&id={string}

    Reboot a USB hub. This is a diagnostic action and should be rarely required.

    Entitlement: Manage USB hubs
    Result: ResultModel

    Query:
    Field Type Description
    id string The serial number of the USB hub to reboot.

    Async Requests

    GET /Async?id={Guid}

    Query an async result's state. See Async for more information.

    Entitlement: none
    Result: AsyncStatus<T>

    Query:
    Field Type Description
    id Guid The async ID.

    Async

    Some requests take longer than a HTTP request can be held open. These requests return an AsyncResponse. The status of the request must then be polled using Get /Async.

    Get Async will return a false value in isComplete until either an error or success occurs, then isComplete will be true, and data will be populated with the result. Once a completed status is returned, the async ID is invalidated and can no longer be used. Async results that have not been polled in 5 minutes are invalidated.

    Metric Schema

    The table names usb_hub, log, health_check, and sample. The column device_id is consistent across all tables.

    usb_hub

    Information regarding the device's USB connection and battery information when available.
    Type Description
    device_id The device ID.
    voltage The current voltage on the USB hub's v5 line.
    amperage The amperage draw the device is placing on the USB hub.
    wattage The wattage draw the device is placing on the USB hub.
    usb_state The state of this USB port. Possible values are Off, Sync, or Charge.
    charging_profile When the device is in Charge state, the profile used by the Cambrionix USB hub to charge the device. No further information is available on this at this time.
    charging_seconds When the number of seconds the device has been in the Charge state.
    battery_percentage If available, the percentage of battery reported by the device.
    battery_status If available, the status of the battery reported by the device. Possible values are Unknown, Charging, Discharging, NotCharging, Full.

    log

    Logs as printed from the device.
    Type Description
    device_id The device ID.
    log The textual contents of the log line.

    health_check

    Health check status for a device. If device health checks are enabled, GigaFox will periodically verify that device communication is working as expected and record the results here.
    Type Description
    device_id The device ID.
    elapsed_seconds The number of seconds taken to complete the health check.
    is_error True if the health check failed, false otherwise.
    failure_reason If a health check failed, an error message.

    sample

    A sample taken from the device. The fields are dynamic, as different devices have different capabilities. There may be fields available that are not listed, and some listed fields may not always be available.
    • iOS and Android
      • device_id
      • Memory
        • Wired
        • Used
        • Free
        • Active
        • Inactive
      • Network
        • Bytes Out
        • Bytes In
        • Bytes Out Per Second
        • Bytes In Per Second
      • CPU
        • Load
        • User Load
        • System Load
    • iOS only
      • Memory
        • VM Swap Used
        • VM Page Out Bytes
        • VM Page In Bytes
      • Disk
        • Bytes Written
        • Bytes Read
        • Bytes Written Per Second
        • Bytes Read Per Second
        • Write Ops Per Second
        • Read Ops Per Second
        • Write Ops
        • Read Ops
      • Network
        • Packets out
        • Packets in
        • Packets In Per Second
        • Packets Out Per Second
      • CPU
        • Nice Load
        • Threads
        • The total sum of threads on all processes.
    • Android only
      The Android only memory metrics can be referenced to from /proc/meminfo in man7.org.
      Graphics information is only available if there's a process that was launched by GigaFox. What entries are available under Graphics varies between Android versions. More information can be found in developer.android.com.
      • Network
        • Errors Out
        • Dropped Out
        • Errors In
        • Dropped In
      • CPU
        • IO Wait Load
        • IRQ Load
        • Frequency
      • Memory
        • Buffers
        • Cached
        • Active (anon)
        • Inactive (anon)
        • Active (file)
        • Inactive (file)
        • User Total (HighTotal)
        • User Free (HighFree)
        • Kernel Total (LowTotal)
        • Kernel Free (LowFree)
        • AnonPages
        • Mapped
        • Kernel Stack
        • Page Tables
        • Commit Limit
        • Committed_AS
        • Vmalloc Total
        • Vmalloc Used
        • Vmalloc Chunk
      • Graphics
        • Total frames rendered
        • Janky frames (count)
        • Janky frames (percent)
        • 90th percentile
        • 95th percentile
        • 99th percentile
        • Number Missed Vsync
        • Number High input latency
        • Number Slow UI thread
        • Number Slow bitmap uploads
        • Number Slow issue draw commands
        • TextureCache Current
        • TextureCache Total
        • LayerCache Current
        • LayerCache Total
        • RenderBufferCache Current
        • RenderBufferCache Total
        • GradientCache Current
        • GradientCache Total
        • PathCache Current
        • PathCache Total
        • TessellationCache Current
        • TessellationCache Total
        • TextDropShadowCache Current
        • TextDropShadowCache Total
        • PatchCache Current
        • PatchCache Total
        • FontRenderer 0 A8 Current
        • FontRenderer 0 A8 Total
        • FontRenderer 0 RGBA Current
        • FontRenderer 0 RGBA Total
        • FontRenderer 0 total Current
        • FontRenderer 0 total Total
        • FboCache Current
        • FboCache Total
        • Total graphics memory

    Models

    Enums

    Enums are passed as strings.

    Type Description
    DeviceAvailabilityStatus Offline, Online
    ApplicationFormFactor Universal, Phone, Tablet
    DeviceBatteryStatus Unknown, Charging, Discharging, NotCharging, Full
    EventType DeviceAvailability, DeviceRetained, DeviceEnablement, DeviceOperatingSystemChange, DeviceDeletion, ApplicationLaunch, ApplicationInstall, SharedViewOnlySessionCreated, UserLogin, UserCreated, ServerStarting, ServerRestarting, Note
    DeviceOperatingSystem Unknown, iOS, Android
    DeviceFormFactor Unknown, Phone, Tablet
    DevicePropertyType System
    UsbHubPortState Unknown, Off, Data, Charge
    UsbHubDeviceFlags None, Off, Sync, Biased, ChargeIdle, ChargeProfiling, ChargeCharging, ChargeFinished, Attached, Detached, Errors, Rebooted, VBusReset

    Models

    Application

    Field Type
    id Guid
    displayName string
    applicationIdentifier string
    version string
    buildVersion string
    Operating System DeviceOperatingSystem
    minimumOperatingSystemVersion string
    applicationBlob string
    originalApplicationBlob string
    fileName string
    remotePort int
    versionCounter int
    iconBlob string
    fileByteCount long
    vendorApplicationName string
    provisionExpirationDate DateTime?
    provisionsAllDevices bool
    signingCertificateName string
    isSigningCertificatePresentInEmbeddedProvisi onProfile bool
    supportedFormFactors ApplicationFormFactor
    applicationErrors string[]
    enabled bool
    createdDate DateTime
    appTeamIdentifier string
    trustDylibTeamIdentifier string
    isTrustDylibEmbeddedInApp bool
    notes string

    Device

    Field Type
    id Guid
    availability DeviceAvailabilityStatus
    retainedById Guid?
    retainedByDisplayName string
    enabled bool
    batteryStatus DeviceBatteryStatus
    batteryPercentCharged int
    diskSpace long
    slotNumber int?
    diskSpaceUsed long
    nextReservationStartTime DateTime?
    nextReservationEndTime DateTime?
    reservedById Guid?
    reservedByDisplayName string
    lastInuseAt DateTime?
    lastDisconnectedAt DateTime?
    lastConnectedAt DateTime?
    deleted bool
    notes string
    retainedByUserName string
    name string
    model string
    operatingSystem DeviceOperatingSystem
    operatingSystemVersion string
    macAddress string
    serialNumber string
    manufacturer string
    friendlyModel string
    vendorUniqueIdentifier string
    vendorDeviceName string
    deviceClass string
    formFactor DeviceFormFactor
    productType string
    isAudioEnabled bool
    hardwareModel string
    operatingSystemBuild string
    usbHubSerialNumber string
    usbHubPortNumber int
    usbLocation string
    bluetoothAddress string
    properties DeviceProperty[]
    application Application[]

    DeviceProperty

    Field Type
    name string
    value string
    type DevicePropertyType

    User

    Field Type
    id Guid
    email string
    isActive bool
    firstName string
    middleName string
    lastName string
    notes string
    organization string
    title string
    location string
    address1 string
    address2 string
    city string
    region string
    postalCode string
    country string
    homePhone string
    mobilePhone string
    officePhone string
    faxPhone string
    createdDate DateTime?
    lastLoginDate DateTime?
    roles string[]
    properties UserProperty[]

    UserProperty

    Field Type
    name string
    value string

    Event

    Field Type
    id Guid
    deviceId Guid?
    deviceName string
    eventType EventType
    EventDate DateTime
    performedById Guid?
    performedByName string
    intValue int
    boolValue bool
    stringValue string
    message string
    isSuccess bool
    propertiesId Guid?
    applicationName string
    userId Guid?
    deviceInuseCount int
    deviceOnlineCount int

    DeviceUsageSummary

    Field Type
    id Guid
    deviceId Guid
    deviceName string
    performedById Guid?
    performedByName string
    applicationId Guid?
    applicationName string
    reservedById Guid?
    reservedByName string
    eventType EventType
    operatingSystem DeviceOperatingSystem
    operatingSystemVersion string
    startDate DateTime
    endDate DateTime
    duration TimeSpan
    isDirty bool

    EventHistory

    Field Type
    count int
    pageSize int
    events Event[]

    DeviceUsageHistory

    Field Type
    count int
    pageSize int
    deviceUsage DeviceUsageSummary[]

    GatewayDescription

    Field Type
    name string
    publicAddress string
    publicPort int
    usbHubList UsbHub[]

    UsbHub

    Field Type
    name string
    location string
    serialNumber string
    description string
    model string
    firmware string
    firmwareDate string
    uptime TimeSpan
    fiveVoltNow double
    fiveVoltMin double
    fiveVoltMax double
    errorMessage string
    isErrored bool
    devices UsbHubDevice[]

    UsbHubDevice

    Field Type
    name string
    location string
    serialNumber string
    usbHubSerialNumber string
    usbHubPortNumber int
    milliamps int
    state UsbHubPortState
    flags UsbHubDeviceFlags
    chargingTime TimeSpan
    chargingProfile string

    DeviceAccessTicket

    Field Type
    authenticator string
    gatewayAddress string
    gatewayPort int
    deviceVendorUniqueIdentifier string
    serialNumber string

    Result<T>

    The success of an action with an optional data component attached. Any model defined as returning ResultModel does not have data at anytime.

    Field Type Description
    isSuccess bool If the query operation was successful.
    errorMessage string? A textual message of the error that happened. Excluded if isSuccess is true.
    data T? The resulting data. Excluded if isSuccess is false.

    AsyncResponse

    Field Type
    asyncResponseId Guid

    AsyncStatus<T>

    Field Type
    isComplete bool
    data T?

    Properties

    Application

    Field Type Uses
    Id Guid query
    displayName string query; update
    ApplicationIdentifier string query
    Version string query
    buildVersion string query
    OperatingSystem string query
    MinimumOperatingSystemVersion string query
    ApplicationBlob string query
    OriginalApplicationBlob string query
    FileName string query

    Device

    Field Type Uses
    Id Guid query
    Name string query; update
    SlotNumber string query; update
    Enabled bool query; update
    Deleted bool query; update
    Notes string update
    OperatingSystem string query
    Availability string query

    User

    Field Type Uses
    Id Guid query
    UserName string query; update
    IsActive string query; update
    FirstName string query; update
    MiddleName string query; update
    LastName string update; update
    Notes string query; update
    Organization string query; update
    Title string query; update
    Location string query; update
    Address1 string query; update
    Address2 string query; update
    City string query; update
    Region string query; update
    PostalCode string query; update
    Country string query; update
    HomePhone string query; update
    MobilePhone string query; update
    OfficePhone string query; update
    FaxPhone string query; update
    Password string update

    AppiumInformation

    Field Type Description
    path string Path of the Appium configuration.
    version string The GigaFox managed patch version.
    pathHash string The GigaFox managed patch version.

    XcodeInformation

    Field Type Description
    path string The Xcode installation path.
    versionString string Xcode version
    version string Xcode version
    buildVersion string The Xcode build version.

    HubInformation

    Field Type Description
    deviceConnectNodeId string The unique licensed node ID of the hub service.
    GigaFoxVersion string The GigaFox version installed on the server.
    systemDateTime DateTime The local date/time of the server.
    systemDateTimeUtc DateTime The UTC date/time of the server.
    deviceGatewayInformation GatewayInformation[] Information regarding the connected device gateway servers.

    DeviceGatewayInformation

    Field Type Description
    GigaFoxId string The unique licensed node ID of the hub service.
    GigaFoxVersion string The GigaFox version installed on the server.
    systemDateTime DateTime The local date/time of the server.
    systemDateTimeUtc DateTime The UTC date/time of the server.
    deviceVendorUniqueIdentifiers string[] The list of vendor unique device IDs attached to this device gateway.
    xcode XcodeInformation[] The Xcode versions available on this device gateway.
    appium AppiumInformation[] The Appium versions available on this device gateway.
    appiumConfigurationError string Any known configuration issues with the Appium installation.

    General

    Field Type Description
    pretty bool? When set to true, data returns with line breaks and whitespace.

    Data Types

    Any data type with a question mark postfix is optional. Generic types are represented with less than greater than brackets. For example, ResultModel<Guid> would be a ResultModel with a data property of Guid.

    Guid

    All Guids are v4 uuids. Most requests in GigaFox refer to objects internally by an assigned Guid. They should be treated no differently than strings.

    Example: 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6

    bool
    A boolean value.
    bool results are always returned as true or false.
    Requests accept boolean values in any case.

    Examples:

    • True
    • true

    String

    Text. A sequence of characters.

    int

    A 32bit signed numerical value. Ranges are -2147483648 to 2147483647.

    long

    A 64bit signed numerical value. Ranges are -9223372036854775808 to 9223372036854775807.

    DateTime

    Represents a date and time combined.
    DateTime results are always given as fully qualified ISO 8601 combined date time stamps in UTC.

    Example: 2016-08-10T08:04:00Z
    Requests accept any format which is valid for .net's DateTime.Parse. The timezone is presumed the server's timezone unless specified.

    Examples:

    • 05/01/2016 14:57:32.8
    • 2016-05-01 14:57:32.8
    • 2016-05-01T14:57:32.8375298-04:00
    • 5/01/2016

    TimeSpan

    TimeSpans are returned as the total number of seconds as a decimal.
    Example: 550000.0