In Listener, the REST API manages entities, such as sources, users, and targets, and also provides Listener status. The REST API has its own hostname, which an administrator sets when installing Listener.
Base URL and Versioning
The REST API is versioned. To make sure the applications that stream data to Listener are compatible, include the API version in the hostname path. For example, https://listener-app-services.YOURCOMPANY.DOMAIN/v1/. For specific domain information, contact your administrator.
All API requests require a valid Authorization header, except the Login endpoint. The header requires a valid token. To obtain a valid token, send a request to the User Login endpoint. For example, Authorization: Bearer VALID_TOKEN.
Certain endpoints are valid for only the administrator or super user, and require a token obtained during login with the appropriate credentials. Users promoted to administrator after login must obtain a new token to access administrator endpoints. A token is valid for five days from the date of issue. When the token expires, delete the cache or stored copy and obtain a new token.
The API accepts and returns the application/json media type for all requests. In requests, declare a content-type: application/json header. Requests with a message-body use plain JSON to set or update resource states.
The API supports CORS requests, which allows browsers to call the API directly from other domains.
All records have an ID in the form of a UUID. Listener UUIDs are version 4 (random). For example, 758fbda4-accc-4f90-8f09-cc0a164c8c28. See https://tools.ietf.org/html/rfc4122 for more information about version 4 UUIDs.
Listener expects all timestamps in the REST API to comply with Date and Time on the Internet: Timestamps in the format of YYYY-MM-DDTHH:MM:SSZ, where all timestamps are in GMT and not localized. For information about supported timestamp formats for ingested messages that are automatically mapped to targets, see Target Mapping.
Listener uses common HTTP response status codes and provides additional information in the response body, if applicable.