Get application versions

GET

/api/v1/applications/{id}/versions

const url = 'http://localhost:3000/api/v1/applications/550e8400-e29b-41d4-a716-446655440000/versions?lifecycleStatus=ACTIVE';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/applications/550e8400-e29b-41d4-a716-446655440000/versions?lifecycleStatus=ACTIVE' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves all versions for an application package.

Authorizations

api-key
bearer

Parameters

Path Parameters

required

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

Application package UUID

Query Parameters

lifecycleStatus

string

Allowed values: ACTIVE DEPRECATED RETIRED

Return only versions in this lifecycle status

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Responses

200

Application versions retrieved successfully

application/json

object

data

required

List of application versions

Array<object>

object

required

Unique identifier for the application description

string

applicationPackageId

required

ID of the parent application package

string

applicationPackageName

required

Name of the parent application package

string

version

required

Version string (semver)

string

deploymentProfile

required

Deployment profile type

string

Allowed values: DOCKER_COMPOSE HELM K8S_MANIFEST PODMAN QUADLET

manifest

required

Full deployment manifest

object

checksumSha256

SHA-256 checksum of the package

string

minMargoVersion

Minimum Margo version required

string

compatibleDevices

required

List of compatible device types/constraints

Array<object>

object

resourceRequirements

required

Resource requirements (CPU, memory, etc.)

object

validationErrors

required

List of validation errors if any

Array<object>

object

usesDeprecatedSchema

required

True when the stored manifest still carries the retired packageLocation/keyLocation component-artifact fields instead of repository+revision (ADR-0010-1 / FM-1090). Such a description will not deploy until republished/resynced under the new schema.

boolean

usesRetiredParameterShape

required

True when the stored manifest still carries the retired parameter shape (parameters[].type/required/validation/description, the array form of parameters, or configuration without schema). Such a description cannot be validated and will not deploy (409 RETIRED_PARAMETER_SHAPE) until republished under Margo rc2 (FM-1280).

boolean

lifecycleStatus

required

Operator-set lifecycle status of this version (FM-1004). RETIRED versions cannot be selected for new deployments; DEPRECATED versions stay deployable.

string

Allowed values: ACTIVE DEPRECATED RETIRED

availability

Application availability status

string

Allowed values: AVAILABLE SOURCE_UNAVAILABLE

sourceLinks

Source repository links for this version

Array<object>

object

registryType

required

Registry type

string

Allowed values: git oci

registryId

required

Registry ID

string

registryName

required

Registry name

string

registryUrl

Registry URL

string

lastSeenAt

required

When the version was last seen in this registry

string

createdAt

required

When this version was created

string

updatedAt

required

When this version was last updated

string

licenseFile

FM-1473: license file path as declared by this version (catalog.application.licenseFile)

string

licenseText

FM-1473: this version’s license content, when the file is text or Markdown

string

releaseNotesFile

FM-1473: release notes file path as declared by this version (catalog.application.releaseNotes)

string

releaseNotesText

FM-1473: this version’s release notes, when the file is text or Markdown

string

tagline

FM-1694: one-line tagline of this version (catalog.application.tagline)

string

site

FM-1694: application website, an absolute http(s) URL (catalog.application.site)

string

organizationSite

FM-1694: organization website, an absolute http(s) URL (catalog.organization.site)

string

total

required

Total number of versions

number

Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "applicationPackageId": "550e8400-e29b-41d4-a716-446655440000",
      "applicationPackageName": "Eclipse Mosquitto",
      "version": "2.0.18",
      "deploymentProfile": "DOCKER_COMPOSE",
      "checksumSha256": "a1b2c3d4e5f6...",
      "minMargoVersion": "1.0.0",
      "usesDeprecatedSchema": false,
      "usesRetiredParameterShape": false,
      "lifecycleStatus": "ACTIVE",
      "availability": "AVAILABLE",
      "sourceLinks": [
        {
          "registryType": "git"
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "licenseFile": "LICENSE.txt",
      "licenseText": "Apache License\nVersion 2.0, January 2004",
      "releaseNotesFile": "release-notes.md",
      "releaseNotesText": "## 12.4.10\n\n- Security fixes",
      "tagline": "Fast, reliable time-series storage",
      "site": "https://example.com/app",
      "organizationSite": "https://example.com"
    }
  ],
  "total": 5
}

403

Forbidden — caller lacks required permission

404

Application not found