GAP Web API
Learn more about the GAP Web API
Introduction
GAP exposes an API to facilitate integrations with third-party systems.
A REST API (Representational State Transfer) exposes application functionality over HTTP using a set of well-defined conventions. Resources are addressed via URLs, and standard HTTP verbs - GET, POST, PUT, PATCH, and DELETE - determine the operation being performed. Requests and responses are typically formatted as JSON, and the API is stateless, meaning each request must contain all the information needed to process it independently.
Authentication
There are two ways to authenticate to the API, Basic Authentication or using your API Key.
Basic Authentication
Using basic authentication is as simple as adding the basic authorization header in each API request.
API Key
The GAP API also supports authentication via an API key. To use your API key with the API, the key should be added to the request header. The key name is "X-GAPAPIKEY".
Obtaining an API Key
From the GAP Portal home screen, click "Options".
Click "Users".
Click the name of the user whose API key you wish to view.
Click "User Account".
The API key is shown at the bottom of this screen. Click "Copy to Clipboard" to copy the API key to the clipboard.
Regenerating an API Key
Regenerating an API key will immediately revoke access for the original key. Once you have regenerated the API key, please update any applications to use the new key.
If the user account is associated with a GAP Guardian app, the app will immediately cease to function. The user will need to deactivate the app and log in again.
From the GAP Portal home screen, click "Options".
Click "Users".
Click the name of the user whose API key you wish to regenerate
Click "User Account".
Click "Generate New API Key".
Click the "Generate New API Key" button.
Limits
Clients may access a maximum of 1,000 results from a single request. This limit is increased to 10,000 in some cases.
Requests for more than the limit will result in a reply with a status code of 200 and a body containing 1,000 records in the format requested.
There are limits to how many calls and changes you can make in a one-hour period. Exceeding these limits will result in HTTP 429 status codes being returned.
The API uses a continuation token to allow the user to request the next page of results.
Continuation Tokens
Some endpoints implement pagination for record retrieval. When additional records are available, a continuation token (X-CONTINUATIONTOKEN) is provided in the response header. Including this token in the header of the subsequent request will return the next set of records.
The following endpoints are paged by 1,000 records per request:
Alerts
Device Log
MO Messages
MT Messages
The following endpoints are paged by 10,000 records per request:
Devices
Users
eTags
Some objects such as Devices and Users support eTags.
An object's eTag can be retrieved via a GET request.
When performing a PUT request, the eTag can be optionally included. When the eTag is included, the underlying object will only be updated if the eTag matches. The object will always be updated if the eTag is not included.
OData Filters
The GAP API provides built-in support for a subset of the Open Data Protocol (OData) query string parameters that a client can use to sort or filter the results.
$filter
Selects entries that match a Boolean expression.
/V2/1234/devices?$filter=contains(FriendlyName, 'MyDevice') /V2/1234/devices?$filter=EmergencyState eq 'Emergency'
$orderby
Orders the results by the specified property.
/V2/1234/devices?$orderby=Name
$skip
Skips the first n elements.
/V2/1234/devices?$skip=2
$top
Returns the first n elements in the list. If combined with $orderby, the list is sorted first, and the first n elements of the sorted list are returned (max 1000).
/V2/1234/devices?$top=10
Webhooks
See Webhooks and Configuring Webhooks for more information.
Last updated