This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

About the REST API

Get oriented with the Endor Labs REST API documentation.

Introduction

You can use the Endor Labs API to build scripts and applications that automate processes, integrate with Endor Labs, and extend Endor Labs. For example, you can use the API to triage findings, build an analytics dashboard, or manage releases.

Each REST API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect. For example, you can find endpoints relating to findings in FindingService.

Getting started with the REST API

If you are new to REST APIs, you may find it helpful to refer to the Quickstart or Getting Started guide for an introduction. For more information, see:

If you are familiar with REST APIs but new to the Endor Labs REST API, you may find it helpful to refer to the authentication documentation. For more information, see:

Further reading

1 - API Versions

Learn how to specify which REST API version to use whenever you make a request to the Endor Labs REST API.

About API versioning

The Endor Labs REST API is versioned. Any breaking changes will be released in a new API version.

New endpoints, fields, and enum values are backwards compatible within the same version.

For every new version of the API that is released, the major version is specified in the URL. For example, https://api.endorlabs.com/v1/namespaces/my_namespace/projects uses version 1 of the endpoint, per the v1 path segment.

Each resources have their versions specified in the field meta.version. For example the following resource has version 1 per the v1 value for the field meta.version.

{
  "meta": {
    "create_time": "2023-12-05T00:04:21.853Z",
    "kind": "Project",
    "name": "https://github.com/my_organization/my_repository.git",
    "update_time": "2024-05-01T16:50:03.830911988Z",
    "version": "v1"
  },
  "uuid": "656e69058032bf0abaaeb681"
}

When using the endorctl command-line tool to access the API, new endpoints, fields, or enum values are not available if your version of endorctl is older than the API version. Make sure to keep endorctl up-to-date to access the latest features and endpoints. For more information, see Install and configure endorctl.

Check latest API version using curl

To check the latest API version using curl, run the following command:

curl -s https://api.endorlabs.com/meta/version | jq .Service.Version

Example request using curl

curl -s https://api.endorlabs.com/meta/version | jq .Service.Version
"v1.6.322"

Check latest endorctl version

To get both the current and the latest version of endorctl, run the following command:

endorctl --version

In addition to your current version of endorctl you will also see a notification such as the following if a newer version of endorctl is available.

Example request using endorctl

endorctl --version
endorctl version v1.6.293
A newer version of endorctl is available v1.6.317 - currently v1.6.293

2 - OpenAPI description

The Endor Labs REST API is fully described in an OpenAPI compliant document.

About OpenAPI

OpenAPI is a specification for describing REST API interfaces. It describes the API as an open standard to act as a dictionary for an API. OpenAPI enables developers to easily find and discover how to use your API. For more information, see the OpenAPI specification documentation.

Using the Endor Labs OpenAPI description

Because the OpenAPI description is machine readable, you can use it to do things like:

  • Generate libraries to facilitate using the REST API
  • Validate and test an integration that uses the REST API
  • Explore and interact with the REST API using third-party tools, such as Postman

For example, Endor Labs uses the OpenAPI description to generate the REST API reference documentation for each endpoint.

For more information, see the Endor Labs OpenAPI documentation.