Quick Start

Postman

The requests from this documentation can be made via Postman

View Postman API Reference

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, Vehicles, 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.

Example:

/vehicles

{
  "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

Status codes

Rates

The API handles limits to the different resources on a per user and global rate for the whole site:

Rawdata & Counters:

• global: 60/minute; 800/hour
• per user: 3/second; 30/minute; 500/hour

Trips:

• global: 120/minute, 1600/hour
• per user: 6/second, 30/minute, 500/hour

Geofences:

• global: 2500/minute
• per user: 125/minute

Geofence Types

• global: 240/minute
• per user: 80/minute

Reversegeo

• global: 1200/minute, 15000/hour
• per user: 200/minute, 4200/hour

Apps Resources

• global: 20/second
• per user: 5/second, 20/minute

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. 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.

// 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.

> 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

👍

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 section which allows you to subscribe to the vehicle's data in realtime or 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:

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, Counters and 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

Allowed values

The API allows you to specify multiple values for each unit of measurement.

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.

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 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 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