Lightrun REST API¶

Introduction¶

The Lightrun API is an HTTP REST API. From Lightrun version 1.29, you can configure REST API commands for the Runtime Reachability feature.

This is how you use the Lightrun REST API using cURL as an example.

/api/v<number>/<entity>/....

You can download cURL here. For information on how to configure and use cURL, click here.

Availability¶

From Lightrun version 1.29, the Lightrun APIs are available as part of the Lightrun Server.

Authentication¶

Lightrun uses API keys to authenticate REST API requests. You manage your API keys directly in the Lightrun Management Portal.

All APIs require authentication. The api-key will be passed via an http header.

curl --header "Authorization: Bearer API-KEY" url

Lightrun returns the following error message with a status code of 401 if authentication information is not valid or missing.

{
  "message": "401 Unauthorized"
}

Data Encryption¶

The communication is encrypted at transit via TLS 1.2 or higher.

Pagination¶

Lightrun supports offset-based pagination, where the default number of records on a page is 10, with a maximum limit of 1000 records.

To modify pagination when listing resources, you can use the offset and limit parameters.

For example, the command to retrieve records 51 through 75, would be:

curl "https://lightrun.com/api/v1/reports?offset=50&limit=25"

HTTP Response Codes¶

Lightrun uses standard HTTP response codes to indicate the success or failure of an API request. The following table provides a list of return codes along with an explanation for each code.

Lightrun API main categories¶

The Lightrun API commands are grouped into the following main categories, representing the core areas of functionality. Each category includes a dedicated set of endpoints, which you can explore in the API Reference:

• Users: Create, update, or delete a user, and retrieve a list of users.

• Users and Groups: Create, update, or delete a group, retrieve a list of user groups, and add group members.

• Just-In-Time Access: Grant temporary access to a list of users and retrieve all users with active temporary access.

• Agent Pools: Create, update, or delete an agent pool, enable agents in an agent pool by ID.

• Dynamic SBOM: Retrieve the Software Bill of Materials (SBOM) as part of the Runtime Reachability feature.

• Loaded Packages: Inspect loaded packages in real time as part of the Runtime Reachability feature.

• Watched Packages: Inspect watched packages in real time as part of the Runtime Reachability feature.

• Lightrun Feature Flags: Get or update a list of feature flags that control which Lightrun features are visible to users.

• Lightrun Actions: Create or delete snapshot, retrieve a list of all actions, and fetch an action by ID.

• System access API Keys: Create, update, or delete a system API Key, and retrieve all API Keys.

• Agents: Retrieve a list of all active agents.

• Identity Management (IdM): Configure authentication sources such as SAML, SCIM, or OAuth for user federation.

• Tags: Retrieve a list of tags assigned in your organization.

• System Connectivity Configuration: Set up SMTP connectivty to Lightrun in your organization.

Get Started¶

To access the Lightrun API, click here.