# 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". {% hint style="info" %} If an API key is used, it takes precedence over basic authentication. {% endhint %} #### Obtaining an API Key {% hint style="info" icon="user-lock" %} This action requires the **Manage Own API Key** and / or **Manage Other Users' API Key** permissions. {% endhint %} 1. From the GAP Portal home screen, click "Options". 2. Click "Users". 3. Click the name of the user whose API key you wish to view. 4. Click "User Account". 5. 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 {% hint style="danger" icon="circle-exclamation" %} 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](/devices/gap-guardian-app/gap-guardian-v3-user-guide.md#deactivation) and log in again. {% endhint %} {% hint style="info" icon="user-lock" %} This action requires the **Manage Own API Key** and / or **Manage Other Users' API Key** permissions. {% endhint %} 1. From the GAP Portal home screen, click "Options". 2. Click "Users". 3. Click the name of the user whose API key you wish to regenerate 4. Click "User Account". 5. Click "Generate New API Key". 6. 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](http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html) that a client can use to sort or filter the results.
ParameterDescriptionExample
$filterSelects entries that match a Boolean expression./V2/1234/devices?$filter=contains(FriendlyName, 'MyDevice')

/V2/1234/devices?$filter=EmergencyState eq 'Emergency'
$orderbyOrders the results by the specified property./V2/1234/devices?$orderby=Name
$skipSkips the first n elements./V2/1234/devices?$skip=2
$topReturns 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 The Webhooks feature allows third-party systems to be notified every time a specified action occurs. Webhooks are currently supported for Devices, Users, Tenants, MO Messages and Event Notifications. Each data item is sent individually soon after the action occurs on GAP. The item is serialized using JSON and includes an indicator of the item type, the action taken, and the item itself. You can choose either basic or no authentication. A retry mechanism is in place that will repeat the call several times until success HTTP status code is received. See [Configuring Webhooks](/administration/integrations/configuring-webhooks.md) for more information. View OpenAPI spec --- # Agent Instructions: 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: ``` GET https://docs.globalalerting.com/web-api/readme.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.