Documentation Powered by ReDoc

Skylight HTTP API (0.3.0)

Download OpenAPI specification:Download

E-mail: developer-skylight@epiqsolutions.com License: UNLICENSED Terms of Service

This is an HTTP API for the Skylight application.

Skylight

All standard endpoints related to the Skylight survey application

Get Skylight Configuration

Retrieves the specified Skylight configuration.

query Parameters
address
string
Example: address=127.0.0.1:7531

The Skylight instance to query.

Responses

200

An object containing Skylight configuration information.

400

The provided `address`` was not valid

504

Skylight did not respond

get /config/
http://127.0.0.1:3030/sklt/config/
http://127.0.0.1:3050/sklt/config/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "database_parameters":
    {
    },
  • "scanner_parameters":
    {
    }
}

Set Skylight Configuration

Sets the specified Skylight configuration. The API user only needs to populate the fields that should be updated. Values that are not specified are left unchanged.

query Parameters
address
string
Example: address=127.0.0.1:7531

The Skylight instance to update.

Request Body schema: application/json

The desired Skylight Configuration.

database_parameters
object

Configuration options for the Skylight database. The database is maintained by the Skylight web server and may contain survey information derived from multiple Skylight scanner instances; each of which is identified by a unique address.

scanner_parameters
object

Configuration information associated with a specific Skylight scanner; identified by address.

Responses

200

An object containing info about Skylight's Survey configuration

400

The provided configuration or address was not valid

504

Skylight did not respond

patch /config/
http://127.0.0.1:3030/sklt/config/
http://127.0.0.1:3050/sklt/config/

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "database_parameters":
    {
    },
  • "scanner_parameters":
    {
    }
}

Get Skylight database status

An object containing information about the current status of the Skylight database.

Responses

200

An object containing information about the current status of the Skylight database.

500

An error occurred while trying to fetch the database status

get /database/status/
http://127.0.0.1:3030/sklt/database/status/
http://127.0.0.1:3050/sklt/database/status/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "scan_results":
    {
    }
}

Get RATs/bands/chans by freq range

This endpoint provides a way to retrieve a set of Radio Access Technologies (RATs) and their corresponding specification defined bands and channels that are defined within a user-specified frequency range.

The returned results are filtered based on which RATs are licensed and compatible with the selected Skylight instance.

query Parameters
low-freq-mhz
required
string
Example: low-freq-mhz=751.0

Defines the low (inclusive) end of the frequency range to search in Megahertz

high-freq-mhz
required
string
Example: high-freq-mhz=753.0

Defines the high (inclusive) end of the frequency range to search in Megahertz

tech
string
Enum: "cdma2k" "gsm" "lte" "nr" "umts"
Example: tech=nr

Specifies one of Skylight's supported RATs. Used to filter out freq-info to just one particular RAT.

gscn-only
string
Example: gscn-only=1

If specified, this option will filter out any NR channels that do not have a corresponding Global Synchronization Channel Number (GSCN). The gscn-only option is only valid if combined with the tech=nr option.

type
string
Enum: "band" "band-chan"
Example: type=band

Indicates whether bands or bands AND channels should be returned. The default is to return both bands and channels (band-chan).

address
required
string
Example: address=127.0.0.1:7531

The desired Skylight instance to query

Responses

200

The requested RATs/bands/channels were retrieved

400

Frequency range or address was not provided or invalid

504

Skylight did not respond

get /freq-info/
http://127.0.0.1:3030/sklt/freq-info/
http://127.0.0.1:3050/sklt/freq-info/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    },
  • {
    }
]

Update Skylight License

Upload a new Skylight License file

Request Body schema: multipart/form-data

The new Skylight License file

metadata
required
object
file
required
string <binary>

The new Skylight License file

Responses

200

The new Skylight License was valid and has been successfully applied. The new Skylight License object is returned in the response body.

400

There was an error processing the provided Skylight license file

404

The Skylight instance at skylight-address was not found

504

Skylight did not respond

post /license/
http://127.0.0.1:3030/sklt/license/
http://127.0.0.1:3050/sklt/license/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address": "127.0.0.1:7531",
  • "license":
    [
    ]
}

Export Logs

Exports all application logs in a gzipped tarball.

Responses

200

The requested export file was generated and returned

500

There was an error packaging the log files for download

504

Skylight did not respond

get /log-export/
http://127.0.0.1:3030/sklt/log-export/
http://127.0.0.1:3050/sklt/log-export/

Get Skylight Status

Retrieves a list of each Skylight instances' status

query Parameters
address
string
Example: address=127.0.0.1:7531

The desired Skylight instance

Responses

200

An object containing all of the info about Skylight's configuration

NOTE: license is null when Skylight did not find a license file

504

Skylight did not respond

get /status/
http://127.0.0.1:3030/sklt/status/
http://127.0.0.1:3050/sklt/status/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get Survey List

Retrieve a list of surveys performed by the Skylight instance specified by skylight-address

query Parameters
address
string
Example: address=127.0.0.1:7531

The desired Skylight instance

Responses

200

A list containing all of the Survey performed by the specified Skylight instance

500

An error occurred while trying to fetch the Survey list

get /survey/
http://127.0.0.1:3030/sklt/survey/
http://127.0.0.1:3050/sklt/survey/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Add a New Survey

Attempts to add a new Survey to the Skylight instance specified by skylight-address

Request Body schema: application/json

The desired Skylight Survey Configuration.

address
required
string

the IP address and port of the Skylight instance <ip-address>:<port>

one_shot
boolean
Default: false

An optional flag that will result in Skylight returning to state == idle after performing a single iteration of the survey. Only valid when the request body contains a configuration with state == scan.

rx_port
required
string

The Rx Port to use for the survey

survey_parameters
required
Array of objects or objects or objects

A list of tech-specific survey parameters, defining which protocols and frequencies Skylight will survey.

file_parameters
object

If present, file_parameters tells Skylight to perform a survey using RF data from a file instead of from a radio; rx_port is ignored. See the Skylight User's Guide for more information about the supported RF data file types and the assumptions and constraints for file-based processing.

Responses

200

An object containing info about the resulting Skylight Survey configuration, which should match what was sent in the request body, with a survey_id and state provided by the server

400

The requested Skylight Survey Configuration was not successfully added.

500

An error occurred while trying to add the new Survey

post /survey/
http://127.0.0.1:3030/sklt/survey/
http://127.0.0.1:3050/sklt/survey/

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address": "127.0.0.1:7531",
  • "one_shot": false,
  • "rx_port": "rx1",
  • "survey_parameters":
    [
    ],
  • "file_parameters":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address": "127.0.0.1:7531",
  • "one_shot": false,
  • "rx_port": "rx1",
  • "survey_parameters":
    [
    ],
  • "file_parameters":
    {
    },
  • "survey_id": "10",
  • "state": "active",
  • "start_date_time": "string",
  • "stop_date_time": "string"
}

Delete All Surveys

Delete all Surveys along with their scan results from the system.

NOTE: Any active surveys will be stopped and deleted

query Parameters
address
string
Example: address=127.0.0.1:7531

The desired Skylight instance.

NOTE: If not provided, all Surveys for all Skylight instances will be deleted.

Responses

204

All Surveys, along with their scan results, were deleted from the system

500

An error occurred while trying to remove the Surveys

delete /survey/
http://127.0.0.1:3030/sklt/survey/
http://127.0.0.1:3050/sklt/survey/

Validate Survey Parameters

Attempts to validate the provided survey_parameters

Request Body schema: application/json

The list of survey_parameters to validate

Array
Any of
  • object
  • object
  • object
tech
required
string
Enum: "cdma2k" "evdo" "gsm" "lte" "nr" "p25" "umts" "wifi"

Specifies one of Skylight's supported technologies

type
required
string
Enum: "band" "frequency-list" "frequency-range"
system_information
Array of strings
Default: null

An optional list specifying which System Information messages Skylight should attempt to decode. Leaving this field unpopulated or empty will result in the default behavior – Skylight will attempt to decode the MIB, SIB1, and SIB2 as well as any other SIBs it finds in the SIB1 schedule.

NOTE: Currently, the only supported option other than the default of null is ["MIB"] which directs Skylight to skip all SIB decoding.

bands
Array of objects

Responses

200

All survey_parameters were valid

400

Not all of the provided survey_parameters were valid

500

An error occurred while trying to validate the Survey

post /survey/validate-survey-parameters/
http://127.0.0.1:3030/sklt/survey/validate-survey-parameters/
http://127.0.0.1:3050/sklt/survey/validate-survey-parameters/

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[ ]

Get Survey

Retrieves the specified Skylight survey configuration.

path Parameters
survey-id
string
Example: 10

The desired Survey's survey-id.

Responses

200

An object containing info about Skylight's Survey configuration

400

The provided survey-id was not valid

404

The Survey was not found

500

An error occurred while trying to fetch the Survey

get /survey/{survey-id}/
http://127.0.0.1:3030/sklt/survey/{survey-id}/
http://127.0.0.1:3050/sklt/survey/{survey-id}/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address": "127.0.0.1:7531",
  • "one_shot": false,
  • "rx_port": "rx1",
  • "survey_parameters":
    [
    ],
  • "file_parameters":
    {
    },
  • "survey_id": "10",
  • "state": "active",
  • "start_date_time": "string",
  • "stop_date_time": "string"
}

Delete a Survey

Deletes the specified Skylight survey and its scan results from the system

NOTE: If the survey is in active state, it will be stopped and deleted unless the force-stop query parameter is set to false.

path Parameters
survey-id
string
Example: 10

The desired Survey's survey-id.

query Parameters
force-stop
boolean
Default: true

If set to false, the specified Survey will not be deleted if it is in active state

Responses

204

The Survey and its scan results were deleted

400

The provided survey-id was not valid

404

The Survey was not found

500

An error occurred while trying to delete the Survey

delete /survey/{survey-id}/
http://127.0.0.1:3030/sklt/survey/{survey-id}/
http://127.0.0.1:3050/sklt/survey/{survey-id}/

Stop a Survey

Set the state of a Survey to stopped

path Parameters
survey-id
string
Example: 10

The desired Survey's survey-id.

Request Body schema: application/json
string
Value: "stopped"

Responses

200

The Survey was stopped

400

The provided 'state' was not valid or acceptable

404

The Survey was not found

500

An error occurred while trying to stop the Survey

put /survey/{survey-id}/state/
http://127.0.0.1:3030/sklt/survey/{survey-id}/state/
http://127.0.0.1:3050/sklt/survey/{survey-id}/state/

Request samples

Content type
application/json
Copy
 Expand all Collapse all
"stopped"

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address": "127.0.0.1:7531",
  • "one_shot": false,
  • "rx_port": "rx1",
  • "survey_parameters":
    [
    ],
  • "file_parameters":
    {
    },
  • "survey_id": "10",
  • "state": "active",
  • "start_date_time": "string",
  • "stop_date_time": "string"
}

Export Survey Results

Exports all Survey Results matching the provided parameters to a file of the specified format.

query Parameters
tech
required
string
Enum: "cdma2k" "evdo" "gsm" "lte" "nr" "p25" "umts" "wifi"
Example: tech=lte

Specifies one of Skylight's supported technologies

type
string
Default: "csv"
Enum: "csv" "gns"

The type of export requested.

address
string
Example: address=192.168.3.1:7531

The desired Skylight instance

survey-id
Array of strings
Example: survey-id=10,11

A set of Survey IDs for the survey(s) that should be exported. When provided, only scan results with a matching survey-id will be included in the results. If omitted, all scans for the provided tech in the database will be returned.

limit
integer

The maximum number of scan records to return

unique-set
Array of strings
Example: unique-set=tech,physical_cell_id

A set of scan parameters for which there should be only one scan returned per unique set of corresponding values.

bands
Array of strings
Example: bands=2,4

A list of bands by which the returned values should be filtered. Only valid when technology is provided

frequency-mhz
Array of numbers <float>
Example: frequency-mhz=1900.5,2050

A list of frequencies (in megahertz) by which the returned values should be filtered.

start-time
string <date-time>
Example: start-time=2023-01-12T06:05:11+0000

An ISO 8601 formatted string specifying a date and time before which no results should be returned

stop-time
string <date-time>
Example: stop-time=2023-01-12T06:05:11+0000

An ISO 8601 formatted string specifying a date and time after which no results should be returned

validate
boolean

Indicates whether scan results should be validated prior to export. Defaults to true. This only applies if the export format has defined field requirements or limits. Note that for file-based surveys it may be necessary to skip validation since absolute RF measurement values are likely incorrect.

Responses

200

The requested export file was generated and returned

400

The provided tech was not valid or the export type is not supported for the specified tech

404

No results were found for the specified tech

504

Skylight did not respond

get /survey-export/
http://127.0.0.1:3030/sklt/survey-export/
http://127.0.0.1:3050/sklt/survey-export/

Get Survey Results

Retrieves any Survey results that match the passed query paramters. If no results are found, an empty array is retuned.

query Parameters
survey-id
Array of strings
Example: survey-id=10,11

A set of Survey IDs for the survey(s) that should be exported. When provided, only scan results with a matching survey-id will be included in the results. If omitted, all scans for the provided tech in the database will be returned.

unique-set
Array of strings
Example: unique-set=tech,physical_cell_id

A set of scan parameters for which there should be only one scan returned per unique set of corresponding values.

technology
string
Enum: "cdma2k" "evdo" "gsm" "lte" "nr" "p25" "umts" "wifi"
Example: technology=lte

Specifies one of Skylight's supported technologies

frequency-mhz
Array of numbers <float>
Example: frequency-mhz=1900.5,2050

A list of frequencies (in megahertz) by which the returned values should be filtered.

Responses

200

The requested survey was found

504

Skylight did not respond

get /survey-results/
http://127.0.0.1:3030/sklt/survey-results/
http://127.0.0.1:3050/sklt/survey-results/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get information about a technology

This endpoint provides a way to get information about the specified technology.

path Parameters
tech
required
string
Enum: "cdma2k" "evdo" "gsm" "lte" "nr" "p25" "umts" "wifi"
Example: lte

Specifies one of Skylight's supported technologies

Responses

200

The technology's information was retrieved

400

Technology was not provided or invalid

504

Skylight did not respond

get /tech-info/{tech}/
http://127.0.0.1:3030/sklt/tech-info/{tech}/
http://127.0.0.1:3050/sklt/tech-info/{tech}/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tech": "lte",
  • "low_mhz": 0,
  • "high_mhz": 0,
  • "band_names":
    [
    ],
  • "bands":
    {
    }
}

Retrieve system time from Skylight host

Retrieves the current system time from the Skylight host machine.

Responses

200

A JSON object containing system time information from the Skylight host machine.

500

Unable to retrieve system time information.

get /time
http://127.0.0.1:3030/sklt/time
http://127.0.0.1:3050/sklt/time

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "time": "2023-01-12T06:05:11+0000"
}

Set the current system time of the Skylight host machine.

Requests an update to the Skylight host system time.
If the Skylight Web Server is hosted on a machine with a 192.168.3.1 IP address at port 8080 then the following curl command could be used to request a system clock change:

$ curl -i -X PUT -H "Content-type: application/json" -H "Accept: application/json" -d '{"time":"2021-10-28T03:47:08Z"}' "http://192.168.3.1:8080/sklt/time/"
\

Request Body schema: application/json
time
required
string <date-time>

Date and time string formatted according to ISO 8601

Responses

200

Successfully set the system time. The returned JSON object contains the current Skylight host system time after processing the request.

400

Setting the Skylight host system time was NOT successful. The returned JSON object contains the current Skylight host system time after processing the request.

put /time
http://127.0.0.1:3030/sklt/time
http://127.0.0.1:3050/sklt/time

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "time": "2023-01-12T06:05:11+0000"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "time": "2023-01-12T06:05:11+0000"
}

Get Skylight Web Server Version Info

Retrieves info about the Web Server version

Responses

200

An object containing info about the Web Server's version

500

An internal error occurred

get /version/
http://127.0.0.1:3030/sklt/version/
http://127.0.0.1:3050/sklt/version/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
"0.3.0"

Websocket

A Websocket is available at the /events/ endpoint and is used to send asynchronous messages to all connected clients. Payloads are string-encoded JSON objects and defined: { source: "Skylight Connection" , data: }

Asynchronous data stream

The Skylight generates asynchronous event messages during the course of normal operations. The Web Server implements a Websocket interface at /events/ that allows interested users to subscribe to this data stream and take actions based on the incoming data.

Responses

200

Data stream is starting.

get /events/
http://127.0.0.1:3030/sklt/events/
http://127.0.0.1:3050/sklt/events/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "data":
    {
    },
  • "source": "Skylight Connection"
}