Player Version Selection

Overview

Fastevo MP2 automatically rolls out compatible player binaries to every project. This guide documents the user-facing endpoints that let you

inspect the catalog of available player versions,
review the release notes for a specific build,
control which versions are eligible for your project, and
optionally configure canary rollouts.

All endpoints live under:

https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/playerVersions

Authentication

Every request must include either a Project API Key or a user bearer token that maps to the project. Set the header just as you do for the rest of the MP2 APIs:

Authorization: Bearer <PROJECT_API_KEY>
Content-Type: application/json

Status Values & Selection Priority

Player versions are published with one of the following statuses:

stable
beta
alpha
deprecated

When your selection does not explicitly match any version (e.g., an empty result for a semver range), MP2 falls back to the best available status in the following order: stable → beta → alpha → deprecated.

Listing Player Versions

GET /

Returns a paginated list of versions visible to the project.

Query Parameters

Parameter	Type	Description
`page`	number	Page index (defaults to `1`).
`limit`	number	Page size (defaults to `10`).
`orderBy`	string	Any of `versionName`, `releasedAt`, `createdAt`, `majorVersion`, `minorVersion`, `patchVersion`.
`order`	string	`asc` or `desc` (defaults to `desc`).
`status`	string	Filter by status (values listed above).
`isLts`	boolean	Only Long Term Support builds when `true`.
`versionName`	string	Case-insensitive substring match.
`releaseNotes`	string	Case-insensitive substring match.
`majorVersion`, `minorVersion`, `patchVersion`	number	Exact numeric filters.

Example

curl -X GET \
  "https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/playerVersions?status=beta&limit=5" \
  -H "Authorization: Bearer $PROJECT_API_KEY"

Sample Response

{
  "currentPage": 1,
  "totalPages": 1,
  "totalRecords": 2,
  "data": [
    {
      "versionName": "test-project-player-version-beta-21000102",
      "status": "beta",
      "releasedAt": "2100-01-02T00:00:00.000Z",
      "releaseNotes": "Beta release for project tests",
      "majorVersion": 100,
      "minorVersion": 1,
      "patchVersion": 0,
      "buildNumber": null,
      "isLts": false,
      "features": ["Beta feature"],
      "bugFixes": [],
      "breakingChanges": [],
      "createdAt": "2025-01-08T15:32:11.242Z",
      "updatedAt": "2025-01-08T15:32:11.242Z"
    }
  ]
}

Retrieving Version Details

GET /{versionName}

Fetches a single record by its exact versionName.

curl -X GET \
  "https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/playerVersions/test-project-player-version-stable-21000101" \
  -H "Authorization: Bearer $PROJECT_API_KEY"

Returns 404 if the version does not exist.

Reading the Current Selection

GET /selection

The response always includes a selection payload. New projects receive the default configuration:

{
  "playerVersionSelection": {
    "versionRange": "latest",
    "allowedStatuses": ["stable"],
    "canaryConfig": {
      "isCanaryEnabled": false,
      "canaryVersionRange": null,
      "canaryTrafficPercentage": 0
    }
  }
}

Updating the Selection

PUT /selection

Provide any combination of versionRange, allowedStatuses, and canaryConfig. Omitted fields retain their previous values.

Request Body Fields

versionRange: accepts "latest", a semantic version (e.g., "2.3.1"), wildcards like "1.*", or semver ranges (e.g., ">=2.0.0 <3.0.0").
allowedStatuses: array of status identifiers listed above.
canaryConfig:
- isCanaryEnabled: boolean flag.
- canaryVersionRange: string range or single version (optional).
- canaryTrafficPercentage: number between 0 and 100.

Example

curl -X PUT \
  "https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/playerVersions/selection" \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionRange": ">=1.0.0 <2.0.0",
    "allowedStatuses": ["beta", "stable"],
    "canaryConfig": {
      "isCanaryEnabled": true,
      "canaryVersionRange": "beta",
      "canaryTrafficPercentage": 15
    }
  }'

Response

{
  "playerVersionSelection": {
    "versionRange": ">=1.0.0 <2.0.0",
    "allowedStatuses": ["beta", "stable"],
    "canaryConfig": {
      "isCanaryEnabled": true,
      "canaryVersionRange": "beta",
      "canaryTrafficPercentage": 15
    }
  }
}

If isCanaryEnabled is true but canaryVersionRange is missing or empty, MP2 disables the canary automatically and preserves the requested traffic percentage. This prevents partially configured rollouts.

Resetting the Selection

DELETE /selection

Clears your overrides and reverts the project to the defaults shown above.

curl -X DELETE \
  "https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/playerVersions/selection" \
  -H "Authorization: Bearer $PROJECT_API_KEY"

The API responds with HTTP 204. Subsequent GET /selection calls reflect the default state (latest + stable + canary disabled).

Tips & Best Practices

Cache refresh: after creating or deleting player versions via admin tools, call GET /selection with forceRefreshCache=true (query string) if you need immediate visibility.
Semver ranges: MP2 uses the Node semver library with prerelease support. Complex expressions such as ">=3.1.0-beta <3.1.0" are valid.
Fallback awareness: even if your range produces no matches, MP2 returns the best candidate within the allowed statuses. Keep this in mind when you expect a “hard fail.”
Canary cohorts: pair canaryVersionRange with SIEM rules or viewer identifiers so you can validate the target version on a stable cohort before broad rollout.

Tracking usage