How to use the Evergreen API

The Evergreen API is provided free of charge - please don't abuse it.

The API is provided on the free tier of Cloudflare Workers which allows up to 100,000 total requests per day. Be kind with your usage of the API so the requests are not exhausted and available for everyone.

Evergreen's difference to other methods of finding and installing applications, is that Evergreen queries only official vendor sources when you use Get-EvergreenApp. This ensures that the information returned can be trusted because it comes from the vendor and is not crowd sourced.

Evergreen supports an API that returns the same application version information as Get-EvergreenApp. The API supports the same applications as the Evergreen module because data is sourced via the module. The API runs on Cloudflare Workers with data that is updated every 24 hours.

Data that is returned by the Evergreen API can be viewed at the Evergreen App Tracker.

Important notes about the API

• The API data is updated once every 24-hours. Requesting data from endpoints too often may be throttled.
• The API is intended for development purposes only and not for use with distributed endpoints (e.g. physical PCs checking for application updates locally).
• If you encounter issues or would prefer to ensure data is only sourced from the application vendor, use Get-EvergreenApp.

Full documentation for the API is available here: evergreen-api; however, if you're familiar with Get-EvergreenApp in the Evergreen module, the API should be easy to use.

Get-EvergreenAppFromApi

Evergreen includes the Get-EvergreenAppFromApi function that is used in much the same way as Get-EvergreenApp. This function is simpler than using Invoke-RestMethod, and it automatically filters for available applications. For example, to query the API for application data for Microsoft Edge, use:

PS C:\> Get-EvergreenAppFromApi -Name "MicrosoftEdge"

Version      : 89.0.774.76
Platform     : Windows
Channel      : Stable
Release      : Enterprise
Architecture : x64
Date         : 12/4/2021
Hash         : 9E7A29B4BE6E1CD707F80B4B79008F19D2D5DD5C774D317A493EC6DE5BE0B7D7
URI          : https://msedge.sf.dl.delivery.mp.microsoft.com/filestreamingservice/files/4d12f620-174c-4259-85e6-8a80ea45ff10/MicrosoftEdgeEnterpriseX64.msi

This returns the current version and download URLs for Microsoft Edge using the official Microsoft Edge update API at https://edgeupdates.microsoft.com/api/products.

Just as with Get-EvergreenApp, the output can be filtered for the specific application installer with Where-Object. The example below returns the current version and download URL for the Stable channel of the 64-bit Enterprise ring of Microsoft Edge.

Get-EvergreenAppFromApi -Name "MicrosoftEdge" | Where-Object { $_.Architecture -eq "x64" -and $_.Channel -eq "Stable" -and $_.Release -eq "Enterprise" }

API Usage

In its current version, the API has only four endpoints that support GET calls and return data in JSON format:

• /apps - returns the list of supported applications
• /app/{appName} - returns details for a specified application
• endpoints/versions - returns the list of URL endpoints used by Evergreen when it connects to vendor sources to return application details (i.e. with Get-EvergreenApp)
• /endpoints/downloads - returns the list of URL endpoints used by Evergreen binaries are downloaded (i.e. with Save-EvergreenApp)

In PowerShell, the API can be queried with Invoke-RestMethod.

A custom user agent is required.

The default user agents of most tools will be blocked to minimise the abuse of the API. Please provide a custom user agent when using tools such as PowerShell, wget, or curl etc. Please specify a custom user agent that will assist in troubleshooting and understand who is using the API (logging data is not made public). For example, specify a custom user agent in the form of "Application/Version (Company/URL)" - e.g., "App-Pipeline/1.0.0 (Contoso; https://contoso.com)", or similar.

Return the list of supported applications from /apps - this is the equivalent of running Find-EvergreenApp:

PS C:\> Invoke-RestMethod -Uri "https://evergreen-api.stealthpuppy.com/apps" -UserAgent "App-Pipeline/1.0.0 (Contoso; https://contoso.com)"

Details for a specific application are returned from the /app/{appName} endpoint along with the name of the supported application.

PS C:\> Invoke-RestMethod -Uri "https://evergreen-api.stealthpuppy.com/app/MicrosoftEdge" -UserAgent "App-Pipeline/1.0.0 (Contoso; https://contoso.com)"

Data returned from the API can be filtered and sent to Save-EvergreenApp to download binaries:

$Edge = Invoke-RestMethod -Uri "https://evergreen-api.stealthpuppy.com/app/MicrosoftEdge" -UserAgent "App-Pipeline/1.0.0 (Contoso; https://contoso.com)"
$Edge | Where-Object { $_.Architecture -eq "x64" -and $_.Channel -eq "Stable" -and $_.Release -eq "Enterprise" } | Save-EvergreenApp -Path "C:\Apps"

If an unknown application is passed to the /app endpoint, an error is returned:

PS C:\> Invoke-RestMethod -Uri "https://evergreen-api.stealthpuppy.com/app/UnsupportedApp" -UserAgent "App-Pipeline/1.0.0 (Contoso; https://contoso.com)"
Invoke-RestMethod:                                                                                                      
{
  "message": "Application not found. Call /apps for a list of available applications.",
  "documentation": "https://eucpilots.com/evergreen/api/"
}