Skip to content

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.

Number Type Description
200 OK Successful transition.
201 Package added to the watch list. Package successfully added to watchlist.
400 Invalid input, object invalid parameters The request failed because it didn't include all the information.
401 Unauthorized API Key is invalid.
402 Request Failed The request failed but the parameters are valid.
409 Watched package already exists The package added to the watch list already is set as watched.

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.


Last update: July 17, 2025