magento-watch Versions API

openapi: 3.2.0
info:
  title: magento.watch Versions API
  version: 1.0.0
  summary: Magento Open Source, Adobe Commerce and Mage-OS version lifecycle data
  description: 'Free, unauthenticated, CORS-open REST API returning release dates, end-of-life dates and system requirements for every tracked Magento Open Source, Adobe Commerce and Mage-OS release. No API key, no rate limit. Responses are cacheable (`Cache-Control: public, max-age=3600, s-maxage=86400`).'
  license:
    name: MIT
    identifier: MIT
  contact:
    name: magento.watch
    url: https://magento.watch/api
servers:
- url: https://magento.watch
  description: Production
security: []
tags:
- name: Versions
  description: Version lifecycle lookups
paths:
  /api/v1/{distribution}/versions:
    get:
      operationId: getVersions
      summary: All tracked releases
      description: Every release recorded for the distribution, each enriched with lifecycle flags computed against the current date and a `securitySummary` with the Adobe security patches the release still needs.
      tags:
      - Versions
      parameters:
      - name: distribution
        in: path
        required: true
        description: Magento distribution slug
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
          - mage-os
        example: magento-community
      responses:
        '200':
          description: All tracked releases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionsResponse'
        '404':
          description: Unknown distribution slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/{distribution}/versions/supported:
    get:
      operationId: getSupportedVersions
      summary: Supported releases
      description: Releases where `isEOLVersion` is false and `isFutureVersion` is false.
      tags:
      - Versions
      parameters:
      - name: distribution
        in: path
        required: true
        description: Magento distribution slug
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
          - mage-os
        example: magento-community
      responses:
        '200':
          description: Supported releases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionsResponse'
        '404':
          description: Unknown distribution slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/{distribution}/versions/secure:
    get:
      operationId: getSecureVersions
      summary: Releases inside their support window
      description: 'Releases where `isSecureVersion` is true and `isFutureVersion` is false. Despite the path, this is the support lifecycle: a release listed here can still have open security bulletins. Read `securitySummary` on each item, or `/versions/{version}/security` for the remedies.'
      tags:
      - Versions
      parameters:
      - name: distribution
        in: path
        required: true
        description: Magento distribution slug
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
          - mage-os
        example: magento-community
      responses:
        '200':
          description: Releases inside their support window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionsResponse'
        '404':
          description: Unknown distribution slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/{distribution}/versions/latest:
    get:
      operationId: getLatestVersion
      summary: Latest release
      description: The single release flagged `isLatestVersion`. `data` still uses the version string as its key.
      tags:
      - Versions
      parameters:
      - name: distribution
        in: path
        required: true
        description: Magento distribution slug
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
          - mage-os
        example: magento-community
      responses:
        '200':
          description: Latest release
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionsResponse'
        '404':
          description: Unknown distribution slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/{distribution}/versions/{version}:
    get:
      operationId: getVersion
      summary: One release by version string
      description: Exact lookup by version key. Unlike the list endpoints, `data` holds the version object directly rather than a keyed map, and embeds a derived `security` summary (same shape as `/security` minus `distribution` and `version`).
      tags:
      - Versions
      parameters:
      - name: distribution
        in: path
        required: true
        description: Magento distribution slug
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
          - mage-os
        example: magento-community
      - name: version
        in: path
        required: true
        description: Exact version key, including any patch suffix
        schema:
          type: string
        example: 2.4.7-p3
      responses:
        '200':
          description: The requested release
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
        '404':
          description: Unknown distribution slug or unknown version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VersionResponse:
      type: object
      required:
      - data
      - _documentation
      - _description
      properties:
        data:
          $ref: '#/components/schemas/MagentoVersionWithSecurity'
        _documentation:
          type: string
          format: uri
          example: https://magento.watch/api
        _description:
          type: string
          example: Version 2.4.7-p3 details
    ListSecuritySummary:
      type: object
      description: Security status of a release in list responses. Remedies live on `/versions/{version}/security`.
      required:
      - status
      - requiredPatches
      - upgradeRequired
      properties:
        status:
          type: string
          enum:
          - vulnerable
          - secure
          - eol
          - unknown
        requiredPatches:
          type:
          - integer
          - 'null'
          minimum: 0
          description: 'Adobe isolated patches that name this exact release. They are not cumulative: all of them are needed, applied oldest first. When `upgradeRequired` is true, upgrade first and use the target release''s own count. Null when no tracked bulletin covers the distribution. Bulletins are tracked from April 2024, so 0 on an end-of-support release does not mean it is safe.'
          example: 4
        upgradeRequired:
          type:
          - boolean
          - 'null'
          description: 'True when an open bulletin has no isolated patch for this exact release: the fix ships in a newer release, or Adobe only patches the newest release of the line. Null when no tracked bulletin covers the distribution.'
          example: false
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          const: not found
    VersionSecuritySummary:
      type: object
      description: VersionSecurityReport without the distribution and version fields, embedded on single-version responses
      required:
      - status
      - vulnerableTo
      - fixedBy
      - recommendedVersion
      properties:
        status:
          type: string
          enum:
          - vulnerable
          - secure
          - eol
          - unknown
        vulnerableTo:
          type: array
          items:
            $ref: '#/components/schemas/VersionSecurityBulletinRef'
        fixedBy:
          type: array
          description: Bulletins already fixed in this release, shipped in it or inherited from an earlier patch of the line. Nothing to install.
          items:
            $ref: '#/components/schemas/VersionSecurityBulletinRef'
        recommendedVersion:
          type:
          - string
          - 'null'
          description: 'Newest release of the same line, or this release when it is the newest. Not a verified safe target: it can have open bulletins of its own.'
          example: 2.4.7-p10
    MagentoVersionWithSecurity:
      allOf:
      - $ref: '#/components/schemas/MagentoVersion'
      - type: object
        required:
        - security
        properties:
          security:
            $ref: '#/components/schemas/VersionSecuritySummary'
    MagentoVersionListItem:
      allOf:
      - $ref: '#/components/schemas/MagentoVersion'
      - type: object
        required:
        - securitySummary
        properties:
          securitySummary:
            $ref: '#/components/schemas/ListSecuritySummary'
    SystemRequirements:
      type: object
      description: Map of kebab-case service key (`php`, `mysql`, `aws-aurora-mysql`, …) to the supported versions of that service. Fully populated per release — never inherited from a parent version.
      additionalProperties:
        type: array
        items:
          type: string
      examples:
      - php:
        - '8.3'
        - '8.4'
        mysql:
        - '8.0'
        aws-s3:
        - supported
    VersionSecurityBulletinRef:
      type: object
      required:
      - id
      - severity
      - publishedDate
      - cves
      - fixedIn
      properties:
        id:
          type: string
          example: APSB24-40
        severity:
          type: string
          enum:
          - critical
          - important
          - moderate
        publishedDate:
          type: string
          format: date
        cves:
          type: array
          items:
            type: string
        fixedIn:
          type:
          - string
          - 'null'
          example: 2.4.7-p1
        isolatedPatches:
          type: array
          items:
            $ref: '#/components/schemas/IsolatedPatch'
    VersionsResponse:
      type: object
      required:
      - data
      - _documentation
      - _description
      properties:
        data:
          type: object
          description: Version string to release object
          additionalProperties:
            $ref: '#/components/schemas/MagentoVersionListItem'
        _documentation:
          type: string
          format: uri
          example: https://magento.watch/api
        _description:
          type: string
          example: Currently supported versions receiving active maintenance
    IsolatedPatch:
      type: object
      required:
      - id
      - appliesTo
      - url
      properties:
        id:
          type: string
        appliesTo:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
    MagentoVersion:
      type: object
      required:
      - version
      - releaseDate
      - eolDate
      - systemRequirements
      - isEOLVersion
      - isSecureVersion
      - isLatestVersion
      - isFutureVersion
      - statusLabel
      properties:
        version:
          type: string
          description: Matches the key this object is stored under
          example: 2.4.7-p3
        releaseDate:
          type:
          - string
          - 'null'
          format: date
          example: '2024-10-08'
        eolDate:
          type:
          - string
          - 'null'
          format: date
          example: '2027-11-01'
        systemRequirements:
          $ref: '#/components/schemas/SystemRequirements'
        isEOLVersion:
          type: boolean
          description: eolDate is in the past
        isSecureVersion:
          type: boolean
          description: 'Neither EOL nor future-dated, so Adobe still ships security fixes for the line. Lifecycle only: it does not mean the release has no open security bulletins; see `securitySummary` or `security`.'
        isLatestVersion:
          type: boolean
          description: True for exactly one release per distribution
        isFutureVersion:
          type: boolean
          description: releaseDate is in the future, or the version is an alpha, beta or RC pre-release
        statusLabel:
          type: string
          enum:
          - pre-release
          - upcoming
          - supported (latest)
          - supported
          - security-only
          - eol
          - unknown