--- updatedAt: 2026-10-07T16:29:34.000Z agentTools: projectIndex: https://pegasus.digitalcomtech.com/llms.txt --- # Quick Start This is a quick start guide into using the Pegasus IoT Cloud platform effectively. ## Postman The requests from this documentation can be made via Postman [Run in Postman](https://god.gw.postman.com/run-collection/389172-41a18a5d-a8ee-4051-b60b-465afbcf6895?action=collection%2Ffork\&collection-url=entityId%3D389172-41a18a5d-a8ee-4051-b60b-465afbcf6895%26entityType%3Dcollection%26workspaceId%3D2d26a2ff-3472-4bde-b215-3f66fc3bd4a4) ### [View Postman API Reference](https://documenter.getpostman.com/view/389172/2s935vnLvt#intro) ## Resource Patterns Resources URI patterns try to follow the general convention: > `/vehicles` - represents all the vehicles *** > `/vehicles/:id` - represents a particular vehicle ID *** > `/vehicles/:id/remote/state` - see the state of a particular vehicle ID *** > `/vehicles/:id/routes` - see the routes of a particular vehicle ID etc. ## Pagination Requests to a collection of resources (such as: [Users](get-data#users), [Vehicles](get-data#vehicles), [Devices](get-data#devices), etc...) are automatically paginated and will return a set of 200 resources by default.
You can request up to 1000 items per page (up to 500 Devices) by using the `set` parameter. When making request to the resources you will see the following additional fields in the response. | field | description | | ------: | ------------------------------- | | `set` | Number of items in current page | | `page` | Current page | | `pages` | Total number of pages | | `total` | Total number of items | | `data` | Actual data | **Example:** > [`/vehicles`](https://api.pegasusgateway.com/vehicles) ```json { "set": 2, "total": 5, "data": [...], "page": 1, "pages": 3 } ``` By default the API returns the first page of result (page: 1), to navigate through the total number of pages pass the parameter `page` until you reach `pages`. Assume we have 252 vehicles, and we make a request to the API without passing parameters, by default it will return the first 200 items: > GET /vehicles ``` { "set": 200, "total": 252, "data": [...], "page": 1, "pages": 2 } ``` If we limit the request to sets of 100, then we'll get a response with 3 pages worth of data, (1 & 2 of 100 and the 3rd page with 52) > GET /vehicles?set=100 ``` { "set": 100, "total": 252, "data": [...], "page": 1, "pages": 3 } ``` To navigate through the pages pass `page` until you reach `pages` > GET /vehicles?set=100\&page=2 ``` { "set": 100, "total": 252, "data": [...], "page": 2, "pages": 3 } ``` > GET /vehicles?set=100\&page=3 ``` { "set": 52, "total": 252, "data": [...], "page": 3, "pages": 3 } ``` Since `page=pages` we are done traversing the items. ## Searching You can search for specific results on the API using the `search` URL param in GET requests. This param works for all resources except for the `/devices` API. ``` # Search for vehicle names that match https://api.pegasusgateway.com/vehicles?search.name=CR2013 # Search for trips reports that are generated daily for the past 7 days https://api.pegasusgateway.com/tasks?search.schedule=[%220%209%20*%20*%20*%22]&search.processes.0.0.script=trips2&search.processes.0.1.back.days=7 ``` ## HTTP Verbs | verb | meaning | | -------: | :-------------------------------------------------------------------- | | `GET` | Used for retrieving resources. | | `POST` | Used for creating resources, sending-info, actions/remote interaction | | `PUT` | Used for replacing/updating resources. | | `DELETE` | Used for deleting resources. | #### Status codes | code | description | meaning | | ---: | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | General success status code. | | 201 | CREATED | Entity has been created (POST request successful). Response body content may or may not be present. | | 204 | NO CONTENT | Status when wrapped responses are not used and nothing is in the body (e.g. DELETE). | | 304 | NOT MODIFIED | Used in response to conditional GET calls to reduce bandwidth usage. | | 400 | BAD REQUEST | General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. | | 401 | UNAUTHORIZED | User is not authenticated with Gateway, does not have permission to upload data, does not have the required scopes, or does not share groups with requested entity | | 403 | FORBIDDEN | User is not allowed to perform operation, regardless of scopes or admin level. | | 404 | NOT FOUND | Used when the requested resource is not found, whether it doesn't exist or if there was a 401 or 403 that, for security reasons, the service wants to mask. | | 409 | CONFLICT | Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries, deleting root objects when cascade-delete not supported are a couple of examples. | | 429 | TOO MANY REQUESTS | Too many requests in a given amount of time, both global limits as well as per-resource and per-user limits apply. See [rates](#rates). | | 500 | INTERNAL SERVER ERROR | Catch-all error when the server-side throws an exception. | ## Rates / Raters The API handles rate limits to the different resources on a per user and global rate for the whole site: [Rawdata](/docs/rawdata) & [Counters](/docs/counters): * global: `60/minute; 800/hour` * per user: `3/second; 30/minute; 500/hour` [Trips](/docs/trips): * global: `120/minute, 1600/hour` * per user: `6/second, 30/minute, 500/hour` [Geofences](platform-data#geofences): * global: `2500/minute` * per user: `125/minute` [Geofence Types](platform-data#geofence-types) * global: `240/minute` * per user: `80/minute` [Reversegeo](reverse-geocoding) * global: `1200/minute, 15000/hour` * per user: `200/minute, 4200/hour` Apps Resources * global: `20/second` * per user: `5/second, 20/minute` Devices * per user: `10/second, 100/minute, 600/hour` Other resources such as vehicles, groups, assets, etc. apply an anti DDOS (Distibuted Denial of Service) limit, which would only be reached if various machines spam the API. Whenever you hit the limit the API returns a [429 Status Code](#status). At which point it is important that your app suspends more subsequent requests to the API until the limit is reset. ### IP Bans If your app continues to make requests after it hits a 429 the API will eventually block the originating IP address. ```json // example response when limit is exceeded and an HTTP 429 is returned { "reason": "vehicles", "message": "Rate exceeded", "limit": 10, "id": "ec2ec6e51a42f40d12e7009787d833b8", "value": 11.0455 } ``` The API returns some response headers which include `X-RateLimit-*` keys so you know when it's safe to make requests again. ```shell > HTTP/1.1 429 TOO MANY REQUESTS > Connection: keep-alive > Content-Length: 135 > Content-Type: application/json > Date: Sun, 30 Sep 2018 16:45:13 GMT > Server: nginx > X-Peg-Id: 1 > X-Peg-Server: F > X-Peg-User-Id: 54 > X-RateLimit-Limit: 10 > X-RateLimit-Remaining: 0 > X-RateLimit-Reset: 1538325923 {reason: "vehicles", message: "Rate exceeded", limit: 10, id: "ec2ec6e51a42f40d12e7009787d833b8",…} ``` The response tells us there's a limit of 10 requests, and the client has 0 remaining, the limit resets back to 10 at the following epoch timestamp: 1538325923 - Sun, 30 Sep 2018 16:45:23 GMT | field | description | | ------: | --------------------------- | | reason | resource that reached limit | | message | description | | limit | amount of request allowed | | id | internal use | | value | rate of requests | | header | description | | --------------------: | -------------------------------------------- | | X-Peg-Id | unique ID for pegasus site | | X-Peg-Server | identification of server (internal use) | | X-Peg-User-Id | user id that made the request | | X-RateLimit-Limit | resource limit | | X-RateLimit-Remaining | amount of requests that remain | | X-RateLimit-Reset | when it's safe to make more requests (epoch) | ### Solutions for rate limiting If your application is on the verge or is constantly hitting the api rate limits you can checkout the [Live Communications](/docs/live-communications) section which allows you to subscribe to the vehicle's data in realtime or [Forwarders](/docs/forwarders) which allows you to receive all the vehicle's data in a JSON format to any external endpoint, for example your own database for further manipulation. ## Units By default the API uses the following units unless otherwise stated: | Metric | Unit | | ----------- | ----------- | | Distance | **meter** | | Volume | **liter** | | Time | **second** | | Temperature | **celsius** | Speed and acceleration units vary per resource, but will normally take the form of * *distance\_unit* / *time\_unit* * *distance\_unit* / *time\_unit* / `second` The API's of [Rawdata](/docs/rawdata), [Counters](/docs/counters) and [Trips](/docs/trips) support unit parameters, which can modify the output to the desired units. ### API Caching Server level caching is done on requests that are similar, therefore it's important to specify the units of a request in order to make it as atomic as possible. [More info below](#caches) #### Allowed values The API allows you to specify multiple values for each unit of measurement. | Parameter | Allowed values | | ------------- | -------------------- | | `distance` | meter, km, mile | | `volume` | liter, gallon | | `time` | second, minute, hour | | `temperature` | C, F | You may also pass `user` for either the `distance` or `volume` parameters, where applicable. The API will return the values in accordance with the users preference. #### Speed Where applicable, the speed is determined by the distance and time units (default: meter/second) The Counters and Trips API's allows you to override this unit, by specifying one of `kph , mph or user`, where `user` falls back to either `kph or mph` based on the users distance preference (mile or km) #### Acceleration The acceleration field is always the speed units, per second * meter/second/second * mile/hour/second. ## Timezones The API by default returns all timestamps in UTC (GMT+0). You can change the timestamp by passing a URL param `tz` with an allowed timezone value or an HTTP header value with`"X-Time-Zone"` and an allowed timezone value. URL param: `tz=America/New_York` HTTP Header: `"X-Time-Zone": "America/New_York"` ## Caches Note that the API does server level caching for similar data requests. If for example you make multiple requests for a vehicle's rawdata with a specific date range the first request will hit the server but any subsequent request will hit the cache and return stored data. To know if a request is cached you can take a look at the response header: `x-cache-status`, which will change to `HIT` when it's a cached request. To take advantage of server level caching it's important that the requests are as atomic as possible, meaning that they're specific enough that it will return the exact results you look for. In other words, pass the units and timezone every time so that you get a cache hit. ## IP Addresses & VPN Info DCT hosts several applications and services that use various IPs to work properly. Depending on what you want to accomplish you may need to pass this information to a Telco or a Network Systems Admin to allow in your networks firewall. Syrus devices that initiate connections with your Pegasus site will use one of the following `entry` IPs: ``` # Syrus Entry Server List # Last Updated: 20-AUG-2024 # Rest of World - 54.92.187.195 - 52.7.79.123 - 35.169.11.229 - 3.220.134.128 - 100.26.92.141 # Europe - 18.193.169.215 ``` ### Telco Additional Information Besides the IPs above you'll need to provide additional information for Telcos in case you're working with a private APN. * Port range: 2001-2200, and port **_5XXX_** * Transport: TCP/UDP * Communication is bidirectional, originating from the device to the platform, and originating from the platform to the device. Where **XXX** is your Pegasus API site ID, which is found in the `/api` resource.
### IP Address Changes Note that DCT will try and maintain these IPs fixed/static for as long as possible so as to not cause any issues with your devices. However in the event that we need to provision a new server DCT may do so without previous knowledge in which case you'll have to contact your Telco to authorize the new IP separately. Whenever possible we recommend using domain names to allow traffic, refer to [below](#firewall-access). Non-Syrus devices from third party manufacturers will use the following ``` # Third Party Devices Server List # Last Updated: 26-AUG-2024 165.227.115.136 142.93.190.241 164.90.132.195 174.138.54.162 143.244.223.241 152.42.152.145 138.197.72.167 ```
### Media Server Note that Syrus devices upload media information (photos, videos) to a separate FTP server. ``` # Media Server # Last Updated: 21-AUG-2024 68.183.146.91 167.71.243.70 167.71.172.120 134.209.173.47 159.203.116.46 165.227.120.10 64.225.54.197 64.225.5.35 138.197.17.45 165.227.103.63 64.225.6.224 64.225.1.105 ``` ### Firewall Access #### Pegasus If you need allow access to Pegasus via a Firewall it's important to use `*.pegasusgateway.com/*` and `*.peginstances.com/*` As any sub-domain from **pegasusgateway.com** and **peginstances.com** are valid. The protocols that we use are HTTP/2 & WebSockets. ### External Services / Plugins Note that within the application there are other requests done to googleapis, gstatic, mapbox, etc. depending on what map provider you have enabled. #### Syrus Cloud For [Syrus Cloud](https://syrus.digitalcomtech.com/docs/syrus-cloud) application you'll need to authorize `*.digitalcomtech.com/*` to access it. Devices will communicate over MQTT to the following domain `*.pegasusgateway.com/*` so you may need to authorize this IP if you're using a private APN ``` # Syrus Cloud MQTT # Last Updated: 26-AUG-2024 165.227.251.57 ```
### Forwarders The source IP address for data that is [Forwarded](https://pegasus.digitalcomtech.com/docs/forwarders) to a destination can vary and is not fixed. If you require a fixed IP address then we can enable a proxy server that uses the following fixed IP. ``` # Forwarder IP Address # Last Updated: 08-OCT-2015 - 159.203.80.12 ```