How To Use the SeaLights Public API Collection (Postman)
Using the SeaLights Public API Postman Collection
This guide will walk you through using the Postman collection provided for our public API. The collection utilizes environment variables to streamline your requests.
Target Audience
This guide is intended for users with a basic understanding of Postman and API interactions.
Prerequisites
A Postman account (free or paid) - https://www.postman.com/
Note: Throughout this guide, we'll use the term "env file" to refer to the Postman environment file.
Importing the Collection
Navigate to our Public API Documentation.
Locate the "Run in Postman" button and click it.
Select your preference: Postman for Web or the Postman Desktop Client.
In this example, we’ll select Postman for Web
Select the workspace into which you want to import the collection and click “Import”
In this example, we’re importing to a workspace named Demo
Setting Up Your Environment
In the Postman sidebar, select Environments. Right-click on the pre-populated environment named "Demo Env" and select Duplicate.
Right-click on "Demo Env Copy" and select Rename.
Choose a descriptive name for your environment (e.g., "CompanyName Env") and save. This will allow you to keep our demo environment file as a boilerplate, should you ever need to create more than one Postman environment.
At the top right of the Postman workspace, click the environment selection dropdown. (If you don't have another environment already set, this will say "No Environment".) Select your new environment "CompanyName Env" from the list.
Next, we'll walk through setting the value of your variables in your new environment
Understanding Environment Variables
The provided "Demo Env" includes several pre-defined variables. THREE of these variables are required for basic API interaction.
SL_DOMAIN: This variable holds the base URL for our API. Be sure to remove a trailing slash from your URL!
e.g.
https://your-domain.sealights.co
SEALIGHTS_API_TOKEN: Found in your SeaLights UI (/settings/tokens/api-tokens).
Click the Gear Icon to access Settings >> From left sidebar: Integration >> API Tokens
SEALIGHTS_AGENT_TOKEN: Found in your SeaLights UI (/settings/tokens/agent-tokens).
Click the Gear Icon to access Settings >> From left sidebar: Cockpit & Onboarding >> Agent Tokens
IMPORTANT: The remaining variables in the "Demo Env" are for demonstration and documentation purposes only. These variables represent query parameters or path variables specific to individual API requests. It's generally recommended to set these directly within each request, not globally in the environment.
Once you have updated your new environment file with these three variables, uncheck the remaining variables in the environment file. This will guard against using “dummy” information throughout the collection. Click “Save” near the top right.
Working with the Collection
Click on Collections in the left sidebar to return to your imported collection.
Select your newly created environment from the dropdown at the top right of the Postman window (if not already set)
Using Requests:
The collection's requests will now utilize the
SL_DOMAIN
,SEALIGHTS_API_TOKEN
, andSEALIGHTS_AGENT_TOKEN
you defined in your environment.Each request may have additional query parameters and/or path variables. These can be updated within the request's Parameters tab.
Only query parameters that are “checked” will be sent with the request
Path variables are always sent with the request
NOTE: The value of variables is not shown in the URL string, but if the variable is set, it will be used when the request is sent. For this reason, in the screenshot above, the value of
:appName
has not been replaced by “DemoApp”, but the query parameter of “offset” is being sent with a value of “3”
REMEMBER: Throughout the collection, variables other than the “Top 3” (such as {{branch_name}}
or {{bsid_var}}
) may be referenced in query parameters and path variables. These are ONLY PLACEHOLDERS. Feel free to overwrite them - they do not need to be managed at the Environment level.
“In-Context” Documentation
Using the “paper” icon found on the right toolbar will reveal additional API documentation without leaving Postman’s interface.
This documentation is context sensitive: what is revealed is based on the endpoint/request you have open.