List applications

GET

/api/v1/applications

const url = 'http://localhost:3000/api/v1/applications?search=mosquitto&category=IoT&vendor=Eclipse%20Foundation&deploymentProfile=DOCKER_COMPOSE&availability=AVAILABLE&lifecycleStatus=ACTIVE&limit=20&offset=0&sortBy=name&sortOrder=asc';
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?search=mosquitto&category=IoT&vendor=Eclipse%20Foundation&deploymentProfile=DOCKER_COMPOSE&availability=AVAILABLE&lifecycleStatus=ACTIVE&limit=20&offset=0&sortBy=name&sortOrder=asc' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves a paginated list of applications with optional filtering by category, vendor, and deployment profile.

Authorizations

api-key
bearer

Parameters

Query Parameters

search

string

Example

mosquitto

Search term to filter applications by name, description, or vendor

category

string

Example

IoT

Filter by category

vendor

string

Example

Eclipse Foundation

Filter by vendor

deploymentProfile

string

Allowed values: DOCKER_COMPOSE HELM K8S_MANIFEST PODMAN QUADLET

Filter by deployment profile type

availability

string

Allowed values: AVAILABLE SOURCE_UNAVAILABLE

Filter by availability status

lifecycleStatus

string

Allowed values: ACTIVE DEPRECATED RETIRED

Filter by version lifecycle status (FM-1004). Matches applications with at least one version in this status.

limit

number

default: 20 >= 1

Maximum number of results to return

offset

number

Number of results to skip

cursor

string

Cursor for pagination

sortBy

string

Allowed values: name updatedAt createdAt

Field to sort by

sortOrder

string

Allowed values: asc desc

Sort order

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

List of applications retrieved successfully

application/json

object

data

required

List of applications

Array<object>

object

required

Unique identifier for the application package

string

organizationId

required

Organization that owns this application

string

name

required

Application name

string

description

Application description

string

descriptionMarkdown

Detailed markdown description of the application

string

releaseNotes

Release notes for the current version

string

descriptionFile

URL or path to detailed description file (Markdown)

string

releaseNotesFile

URL or path to release notes file (Markdown or PDF)

string

licenseFile

URL or path to license file (text, Markdown, or PDF)

string

licenseText

Inline license text content

string

vendor

Vendor/author name

string

category

Category classification

string

iconUrl

URL to application icon

string

availability

Application availability status

string

Allowed values: AVAILABLE SOURCE_UNAVAILABLE

metadata

required

Additional metadata

object

versionCount

required

Number of versions available

number

latestVersion

Latest version string

string

createdAt

required

When the package was created

string

updatedAt

required

When the package was last updated

string

latestDescription

Details of the latest version

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

versionLifecycleStatuses

Distinct lifecycle statuses of the application’s versions (FM-1004). Set on list responses.

Array<string>

Allowed values: ACTIVE DEPRECATED RETIRED

total

required

Total number of applications matching the query

number

hasMore

required

Whether there are more results available

boolean

nextCursor

Cursor for fetching the next page

string

Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Eclipse Mosquitto",
      "description": "Lightweight MQTT broker for IoT",
      "descriptionMarkdown": "# Mosquitto\n\nLightweight MQTT broker for IoT deployments.",
      "releaseNotes": "## Version 2.0.18\n\n- Security fixes\n- Performance improvements",
      "descriptionFile": "/api/v1/applications/550e8400.../files/description",
      "releaseNotesFile": "/api/v1/applications/550e8400.../files/release-notes",
      "licenseFile": "/api/v1/applications/550e8400.../files/license",
      "licenseText": "MIT License\n\nCopyright (c) 2024...",
      "vendor": "Eclipse Foundation",
      "category": "IoT",
      "iconUrl": "/api/v1/applications/550e8400.../icon",
      "availability": "AVAILABLE",
      "versionCount": 3,
      "latestVersion": "2.0.18",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "latestDescription": {
        "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"
      },
      "versionLifecycleStatuses": [
        "ACTIVE"
      ]
    }
  ],
  "total": 42,
  "hasMore": true,
  "nextCursor": "eyJpZCI6IjEyMzQ1In0="
}

401

Unauthorized - Invalid or missing authentication

403

Forbidden — caller lacks required permission

503

Service unavailable - Application service is not reachable