magento-watch Upstream Fixes API

openapi: 3.2.0
info:
  title: magento.watch Upstream Fixes 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: upstream-fixes
  description: Community fixes merged upstream, not yet in a release line; not Adobe Quality Patches
paths:
  /api/v1/{distribution}/versions/{version}/upstream-fixes:
    get:
      operationId: getVersionUpstreamFixes
      summary: All upstream fixes applicable to a version
      description: 'Community fixes merged upstream whose `affectedVersions` include this release, sorted by `pr.mergedAt` descending. Mage-OS returns `status: "unknown"` until its tags are checked separately.'
      tags:
      - upstream-fixes
      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
        example: 2.4.7-p5
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: All upstream fixes applicable to a version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamFixSearchResponse'
        '404':
          description: Unknown distribution or version absent from its data file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/upstream-fixes/search:
    get:
      operationId: getUpstreamFixSearch
      summary: Search upstream fixes for a version
      tags:
      - upstream-fixes
      parameters:
      - name: distribution
        in: query
        required: true
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
          - mage-os
      - name: version
        example: 2.4.7-p5
        in: query
        required: true
        schema:
          type: string
      - name: query
        example: catalog price index
        in: query
        required: false
        schema:
          type: string
      - name: modules
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        description: Repeated or comma-separated component names; boosts ranking
      - name: categories
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        description: Repeated or comma-separated QPT category names; boosts ranking
      - name: fixedIn
        in: query
        required: false
        schema:
          type: string
        description: Restrict to fixes whose `fixedIn` is this release
      - name: includeExcluded
        description: Accepts true/1 or false/0 (case-insensitive); defaults to false
        in: query
        required: false
        schema:
          type: boolean
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
      responses:
        '200':
          description: Search upstream fixes for a version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamFixSearchResponse'
        '400':
          description: Invalid search input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
  /api/v1/upstream-fixes/{id}/composer.zip:
    get:
      operationId: getUpstreamFixComposerBundle
      summary: Download a composer-patches bundle for an upstream fix
      tags:
      - upstream-fixes
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: magento2-40867
      - name: version
        in: query
        required: true
        schema:
          type: string
        example: 2.4.7-p5
        description: Exact version the fix applies to; the merge commit diff is stripped and split per package.
      - name: distribution
        in: query
        required: true
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
      - name: ref
        in: query
        required: false
        schema:
          type: string
        description: First 12 characters of `pr.headCommit` enables immutable caching; absent or stale values use the regular cache policy.
      - name: includeUnmatched
        in: query
        required: false
        schema:
          type: boolean
        description: Accepts true/1 or false/0 (case-insensitive); returns a fix for a version outside `affectedVersions` when true.
      responses:
        '200':
          description: ZIP with README, Composer snippet and package-relative patch files
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          description: Missing version or missing/invalid distribution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Unknown fix or version outside affected versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Upstream diff unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/upstream-fixes/{id}/composer/{vendor}/{file}:
    get:
      operationId: getUpstreamFixComposerFile
      summary: Download one package-relative upstream fix file
      tags:
      - upstream-fixes
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: magento2-40867
      - name: vendor
        in: path
        required: true
        schema:
          type: string
        example: magento
      - name: file
        in: path
        required: true
        schema:
          type: string
        example: module-catalog.patch
      - name: version
        in: query
        required: true
        schema:
          type: string
        example: 2.4.7-p5
        description: Exact version the fix applies to; the merge commit diff is stripped and split per package.
      - name: distribution
        in: query
        required: true
        schema:
          type: string
          enum:
          - magento-community
          - magento-commerce
      - name: ref
        in: query
        required: false
        schema:
          type: string
        description: First 12 characters of `pr.headCommit` enables immutable caching; absent or stale values use the regular cache policy.
      - name: includeUnmatched
        in: query
        required: false
        schema:
          type: boolean
        description: Accepts true/1 or false/0 (case-insensitive); returns a fix for a version outside `affectedVersions` when true.
      responses:
        '200':
          description: Patch with paths relative to the Composer package root
          content:
            text/x-diff:
              schema:
                type: string
        '400':
          description: Missing version or missing/invalid distribution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Unknown fix, unmatched version or missing package file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Upstream diff unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/upstream-fixes/{id}:
    get:
      operationId: getUpstreamFix
      summary: One upstream fix by id
      tags:
      - upstream-fixes
      parameters:
      - name: id
        example: magento2-40867
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: One upstream fix by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamFixResponse'
        '404':
          description: Unknown fix id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/upstream-fixes:
    get:
      operationId: getUpstreamFixes
      summary: All upstream fixes keyed by id
      description: Community bug fixes merged into `magento/magento2` since 2022-01-01, with tag ancestry, code matching and Composer delivery. Excluded entries remain in the file.
      tags:
      - upstream-fixes
      responses:
        '200':
          description: All upstream fixes keyed by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamFixesResponse'
components:
  schemas:
    UpstreamFix:
      type: object
      required:
      - id
      - source
      - sourceRef
      - title
      - pr
      - issues
      - fixedIn
      - containingTags
      - reportedOn
      - codeMatch
      - affectedVersions
      - components
      - files
      - stripped
      - linesChanged
      - mergeBatched
      - excluded
      - sections
      - signatures
      - labels
      - categories
      - triage
      - curated
      - tests
      properties:
        id:
          type: string
          example: magento2-40867
        source:
          $ref: '#/components/schemas/UpstreamFixSource'
        sourceRef:
          type: string
          example: magento/magento2#40867
        title:
          type: string
        pr:
          $ref: '#/components/schemas/UpstreamFixPr'
        issues:
          type: array
          items:
            $ref: '#/components/schemas/UpstreamFixIssue'
        fixedIn:
          type:
          - string
          - 'null'
          example: 2.4.8-p1
        containingTags:
          type: array
          items:
            type: string
        reportedOn:
          type:
          - string
          - 'null'
          example: 2.4.6-p6
        codeMatch:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CodeMatch'
        affectedVersions:
          type: array
          items:
            type: string
        components:
          type: array
          items:
            type: string
        files:
          type: array
          items:
            $ref: '#/components/schemas/UpstreamFixFile'
        stripped:
          $ref: '#/components/schemas/UpstreamFixStripped'
        linesChanged:
          type: integer
        mergeBatched:
          type: boolean
        excluded:
          oneOf:
          - $ref: '#/components/schemas/UpstreamFixExclusion'
          - type: 'null'
        sections:
          $ref: '#/components/schemas/UpstreamFixSections'
        signatures:
          type: array
          items:
            type: string
        labels:
          $ref: '#/components/schemas/UpstreamFixLabels'
        categories:
          type: array
          items:
            type: string
        triage:
          oneOf:
          - $ref: '#/components/schemas/UpstreamFixTriage'
          - type: 'null'
        curated:
          oneOf:
          - $ref: '#/components/schemas/UpstreamFixCurated'
          - type: 'null'
        tests:
          oneOf:
          - type: object
            additionalProperties:
              $ref: '#/components/schemas/UpstreamFixTests'
          - type: 'null'
    UpstreamFixSections:
      type: object
      required:
      - description
      - stepsToReproduce
      - expectedResult
      - actualResult
      - source
      properties:
        description:
          type:
          - string
          - 'null'
        stepsToReproduce:
          type:
          - string
          - 'null'
        expectedResult:
          type:
          - string
          - 'null'
        actualResult:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
          enum:
          - issue
          - pr
          - null
    FindUpstreamFixResult:
      type: object
      required:
      - status
      - mode
      - distribution
      - version
      - hits
      - coverage
      properties:
        status:
          type: string
          enum:
          - ok
          - unknown
          - unknown-version
        mode:
          type: string
          enum:
          - list
          - ranked
        distribution:
          type: string
        version:
          type: string
        hits:
          type: array
          items:
            $ref: '#/components/schemas/UpstreamFixHit'
        knownVersions:
          type: array
          items:
            type: string
        coverage:
          type: object
          required:
          - magento2Commit
          - tags
          - entries
          - excluded
          properties:
            magento2Commit:
              type: string
            tags:
              type: integer
            entries:
              type: integer
            excluded:
              type: integer
    CodeMatch:
      type: string
      enum:
      - clean
      - conflict
      - file-missing
      - error
    UpstreamFixLabels:
      type: object
      required:
      - area
      - component
      - priority
      - severity
      - reportedOn
      properties:
        area:
          type: array
          items:
            type: string
        component:
          type: array
          items:
            type: string
        priority:
          type:
          - string
          - 'null'
        severity:
          type:
          - string
          - 'null'
        reportedOn:
          type: array
          items:
            type: string
    UpstreamFixFile:
      type: object
      required:
      - path
      - change
      - package
      properties:
        path:
          type: string
        change:
          type: string
          enum:
          - modified
          - added
          - deleted
          - renamed
        package:
          type: string
        from:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          const: not found
    UpstreamFixTests:
      type: object
      description: 'fail to pass: fails before, passes after. not-runnable to pass: test could not run before the patch, passes after (the test references code the patch adds, or its file did not apply to this release). not-runnable to error: test files do not apply to this release. pass to pass: passes before and after (test does not cover the fix), a warning. Other passing before or non-passing after outcomes are warnings retaining the after value. adapted adds (test header adapted).'
      required:
      - before
      - after
      - adapted
      - runAt
      - releaseCommit
      properties:
        suites:
          type: object
          description: Per-suite outcomes underlying the aggregate runtime result.
          additionalProperties: false
          properties:
            unit:
              type: object
              required:
              - before
              - after
              properties:
                before:
                  type: string
                  enum:
                  - fail
                  - pass
                  - not-runnable
                after:
                  type: string
                  enum:
                  - pass
                  - fail
                  - error
            integration:
              type: object
              required:
              - before
              - after
              properties:
                before:
                  type: string
                  enum:
                  - fail
                  - pass
                  - not-runnable
                after:
                  type: string
                  enum:
                  - pass
                  - fail
                  - error
            api-functional:
              type: object
              required:
              - before
              - after
              properties:
                before:
                  type: string
                  enum:
                  - fail
                  - pass
                  - not-runnable
                after:
                  type: string
                  enum:
                  - pass
                  - fail
                  - error
        before:
          type: string
          enum:
          - fail
          - pass
          - not-runnable
        after:
          type: string
          enum:
          - pass
          - fail
          - error
          description: error means the code patch did not apply or the suite could not run after it.
        adapted:
          type: boolean
        runAt:
          type: string
          format: date-time
          description: RFC 3339 timestamp; fractional seconds and numeric offsets or Z are accepted. Stored as UTC Z with millisecond precision.
        releaseCommit:
          type: string
    UpstreamFixesResponse:
      type: object
      required:
      - data
      - _meta
      - _documentation
      - _description
      properties:
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpstreamFix'
        _meta:
          $ref: '#/components/schemas/UpstreamFixesMeta'
        _documentation:
          type: string
          format: uri
        _description:
          type: string
    UpstreamFixSource:
      type: string
      enum:
      - github-pr
    UpstreamFixTriage:
      type: object
      required:
      - model
      - requestHash
      - isBugfix
      - changeKind
      - scope
      - risk
      - area
      - securityRelevant
      - reportedVersion
      - backportWorthy
      properties:
        model:
          type: string
        requestHash:
          type: string
        isBugfix:
          type: number
        changeKind:
          $ref: '#/components/schemas/ClefChoice'
        scope:
          $ref: '#/components/schemas/ClefScore'
        risk:
          $ref: '#/components/schemas/ClefScore'
        area:
          $ref: '#/components/schemas/ClefChoice'
        securityRelevant:
          type: number
        reportedVersion:
          $ref: '#/components/schemas/ClefChoice'
        backportWorthy:
          $ref: '#/components/schemas/ClefScore'
    UpstreamFixSearchResponse:
      type: object
      required:
      - data
      - _documentation
      - _description
      properties:
        data:
          $ref: '#/components/schemas/FindUpstreamFixResult'
        _documentation:
          type: string
          format: uri
        _description:
          type: string
    UpstreamFixResponse:
      type: object
      required:
      - data
      - _documentation
      - _description
      properties:
        data:
          $ref: '#/components/schemas/UpstreamFix'
        _documentation:
          type: string
          format: uri
        _description:
          type: string
    ClefChoice:
      type: object
      required:
      - choice
      - probabilities
      - confidence
      properties:
        choice:
          type: string
        probabilities:
          type: object
          additionalProperties:
            type: number
        confidence:
          type: number
    UpstreamFixStripped:
      type: object
      required:
      - tests
      - docs
      - outsideCode
      properties:
        tests:
          type: array
          items:
            type: string
        docs:
          type: array
          items:
            type: string
        outsideCode:
          type: array
          items:
            type: string
    UpstreamFixesMeta:
      type: object
      required:
      - magento2
      - since
      - tags
      - knownVersions
      - generatedAt
      - generator
      - maintainers
      - counts
      properties:
        magento2:
          type: object
          required:
          - commit
          - sweptAt
          properties:
            commit:
              type: string
            sweptAt:
              type: string
              format: date-time
        since:
          type: string
          format: date
        tags:
          type: array
          items:
            type: object
            required:
            - name
            - commit
            properties:
              name:
                type: string
              commit:
                type: string
        knownVersions:
          type: array
          items:
            type: string
        generatedAt:
          type: string
          format: date
        generator:
          type: string
        maintainers:
          type: array
          items:
            type: object
            required:
            - name
            - github
            properties:
              name:
                type: string
              github:
                type: string
        counts:
          type: object
          required:
          - entries
          - excluded
          - byFixedIn
          - byCodeMatch
          properties:
            entries:
              type: integer
            excluded:
              type: integer
            byFixedIn:
              type: object
              additionalProperties:
                type: integer
            byCodeMatch:
              type: object
              required:
              - clean
              - conflict
              - file-missing
              - error
              properties:
                clean:
                  type: integer
                conflict:
                  type: integer
                file-missing:
                  type: integer
                error:
                  type: integer
    UpstreamFixInstall:
      type: object
      required:
      - composer
      properties:
        composer:
          type: object
          required:
          - zipUrl
          properties:
            zipUrl:
              type: string
              format: uri
    UpstreamFixIssue:
      type: object
      required:
      - number
      - url
      - title
      - labels
      - kind
      properties:
        number:
          type: integer
        url:
          type: string
          format: uri
        title:
          type: string
        labels:
          type: array
          items:
            type: string
        kind:
          $ref: '#/components/schemas/IssueKind'
    UpstreamFixHit:
      type: object
      required:
      - id
      - title
      - prUrl
      - issueUrls
      - fixedIn
      - reportedOn
      - codeMatch
      - tests
      - affectedVersions
      - components
      - categories
      - labels
      - issueKind
      - excluded
      - install
      properties:
        id:
          type: string
        score:
          type: integer
        title:
          type: string
        prUrl:
          type: string
          format: uri
        issueUrls:
          type: array
          items:
            type: string
            format: uri
        fixedIn:
          type:
          - string
          - 'null'
        reportedOn:
          type:
          - string
          - 'null'
        codeMatch:
          oneOf:
          - $ref: '#/components/schemas/CodeMatch'
          - type: 'null'
        tests:
          description: Runtime test evidence for the requested version; null when no result is recorded. Passing tests are not a safety claim.
          oneOf:
          - $ref: '#/components/schemas/UpstreamFixTests'
          - type: 'null'
        affectedVersions:
          type: array
          items:
            type: string
        components:
          type: array
          items:
            type: string
        categories:
          type: array
          items:
            type: string
        labels:
          $ref: '#/components/schemas/UpstreamFixLabels'
        issueKind:
          $ref: '#/components/schemas/IssueKind'
        excluded:
          oneOf:
          - $ref: '#/components/schemas/UpstreamFixExclusion'
          - type: 'null'
        triage:
          oneOf:
          - type: object
            required:
            - changeKind
            - risk
            - backportWorthy
            properties:
              changeKind:
                type: string
              risk:
                type: number
              backportWorthy:
                type: number
          - type: 'null'
        install:
          $ref: '#/components/schemas/UpstreamFixInstall'
        matchedOn:
          type: array
          items:
            type: string
    ClefScore:
      type: object
      required:
      - score
      - probabilities
      - confidence
      properties:
        score:
          type: number
        probabilities:
          type: object
          additionalProperties:
            type: number
        confidence:
          type: number
    UpstreamFixCurated:
      type: object
      required:
      - title
      - description
      - categories
      - author
      - date
      - reviewedBy
      properties:
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        categories:
          type: array
          items:
            type: string
        author:
          type: string
        date:
          type: string
          format: date
        reviewedBy:
          type:
          - string
          - 'null'
    UpstreamFixExclusion:
      type: string
      description: 'Why the entry is left out of default lists and search. `not-bugfix`: no linked issue is confirmed and Clef triage does not classify the change as a bug fix.'
      enum:
      - test-only-or-non-code
      - change-kind
      - feature-request-label
      - not-bugfix
    IssueKind:
      type: string
      enum:
      - human
      - pr-derived
    UpstreamFixPr:
      type: object
      required:
      - number
      - url
      - author
      - mergedAt
      - mergeCommit
      - headCommit
      - baseRef
      - diffSha256
      properties:
        number:
          type: integer
        url:
          type: string
          format: uri
        author:
          type: string
        mergedAt:
          type: string
          format: date-time
        mergeCommit:
          type: string
        headCommit:
          type: string
        baseRef:
          type: string
        diffSha256:
          type: string
          pattern: ^[a-f0-9]{64}$
          description: SHA-256 of the pull request diff (`pull/{number}.diff`) the dataset was built from; delivery refuses a diff that no longer hashes to it.
    ValidationError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: What was wrong with the request