Packages

Review package upgrades

Compare the versions you currently use with proposed upgrades for up to 30 packages. Each review brings together security advisories, dependency changes, compatibility information, and release notes to help you decide what to upgrade.

Reviews identify gaps in the available information so you can see where an upgrade needs further investigation.

Selector catalogue

Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.

Selector	Data	Default
`security.direct`	Security advisories for the current and target versions, including advisories introduced, fixed, or unchanged by the upgrade.	Yes
`security.transitive`	Security changes in indirect dependencies, with counts and affected package details. Each detail list includes up to 50 packages and indicates truncation.	Yes
`dependencies.direct`	Direct dependencies added, removed, or changed, including version constraints and resolved versions.	Yes
`dependencies.transitive`	Indirect dependencies added, removed, or changed.	Yes
`dependencies.issues`	Counts and names of newly deprecated, duplicate, conflicting, or outdated dependencies.	No
`compatibility`	Peer dependency changes and compatibility notes.	Yes
`changelog`	Release-note summaries, previews, sources, and change signals for the upgrade range. Entry and keyword-match lists each contain up to 20 items, with coverage and truncation information.	Yes
`changelog.body`	Full release-note text for entries and keyword matches. Also includes changelog.	Yes
`security.*`	Both direct and transitive security groups.	No
`dependencies.*`	All dependency change and issue groups.	No
`changelog.*`	Changelog summaries and full release-note text.	No

POST

package-upgrade-reviews

Review package upgrades

curl --request POST \
  --url https://api.githits.dev/v1/package-upgrade-reviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "packages": [
    {
      "current_version": "1.0.0",
      "name": "example",
      "registry": "npm",
      "target_version": "2.0.0"
    }
  ]
}
'

import requests

url = "https://api.githits.dev/v1/package-upgrade-reviews"

payload = { "packages": [
        {
            "current_version": "1.0.0",
            "name": "example",
            "registry": "npm",
            "target_version": "2.0.0"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    packages: [
      {
        current_version: '1.0.0',
        name: 'example',
        registry: 'npm',
        target_version: '2.0.0'
      }
    ]
  })
};

fetch('https://api.githits.dev/v1/package-upgrade-reviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.githits.dev/v1/package-upgrade-reviews",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'packages' => [
        [
                'current_version' => '1.0.0',
                'name' => 'example',
                'registry' => 'npm',
                'target_version' => '2.0.0'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.githits.dev/v1/package-upgrade-reviews"

	payload := strings.NewReader("{\n  \"packages\": [\n    {\n      \"current_version\": \"1.0.0\",\n      \"name\": \"example\",\n      \"registry\": \"npm\",\n      \"target_version\": \"2.0.0\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.githits.dev/v1/package-upgrade-reviews")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"packages\": [\n    {\n      \"current_version\": \"1.0.0\",\n      \"name\": \"example\",\n      \"registry\": \"npm\",\n      \"target_version\": \"2.0.0\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.githits.dev/v1/package-upgrade-reviews")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"packages\": [\n    {\n      \"current_version\": \"1.0.0\",\n      \"name\": \"example\",\n      \"registry\": \"npm\",\n      \"target_version\": \"2.0.0\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "reviews": [
    {
      "changelog": {
        "breaking_signals": [],
        "entries": [
          {
            "body": "Release notes",
            "body_preview": "Release notes",
            "detail_source": "releases",
            "has_changelog": true,
            "headline": "Release",
            "html_url": null,
            "published_at": null,
            "signals": [],
            "source_version": "v2.0.0",
            "version": "2.0.0"
          }
        ],
        "fallback": null,
        "has_release_note_bodies": true,
        "keyword_entries": [],
        "migration_signals": [],
        "source": "releases",
        "total_entries": 1,
        "total_entries_with_bodies": 1,
        "total_keyword_entries": 0,
        "truncated": false
      },
      "compatibility": {
        "notes": [],
        "peer_dependency_changes": []
      },
      "current_version": "1.0.0",
      "dependency_changes": {
        "direct": {
          "added": [],
          "changed": [],
          "removed": []
        },
        "transitive": {
          "added": [],
          "changed": [],
          "removed": []
        }
      },
      "dependency_issues": {
        "current_total": 0,
        "introduced_conflicts": [],
        "introduced_deprecated": [],
        "introduced_duplicates": [],
        "introduced_outdated": [],
        "target_total": 0
      },
      "name": "example",
      "registry": "npm",
      "security": {
        "current": {
          "advisories": [],
          "affected_count": 0,
          "all_count": 0,
          "deprecated": false,
          "deprecation_reason": null,
          "last_modified_at": null,
          "non_affecting_count": 0,
          "published_at": null,
          "version": "1.0.0"
        },
        "fixed": [],
        "introduced": [],
        "target": {
          "advisories": [],
          "affected_count": 0,
          "all_count": 0,
          "deprecated": false,
          "deprecation_reason": null,
          "last_modified_at": null,
          "non_affecting_count": 0,
          "published_at": null,
          "version": "2.0.0"
        },
        "transitive": {
          "current_affected": 0,
          "fixed_package_details": {
            "entries": [],
            "total_count": 0,
            "truncated": false
          },
          "fixed_packages": [],
          "introduced_package_details": {
            "entries": [],
            "total_count": 0,
            "truncated": false
          },
          "introduced_packages": [],
          "still_affected_package_details": {
            "entries": [],
            "total_count": 0,
            "truncated": false
          },
          "target_affected": 0
        },
        "unchanged": []
      },
      "target_version": "2.0.0",
      "unknown_details": [],
      "version_delta": "major"
    }
  ],
  "total": 1
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version

string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent

string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID

string

Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created.

Query Parameters

fields

string

default:security.direct,security.transitive,dependencies.direct,dependencies.transitive,compatibility,changelog,changelog.body

Finite comma-separated atomic groups. Explicit selection replaces defaults; see catalogue.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

Body

application/json

Ordered canonical batch; unknown/duplicate JSON keys fail validation; rows are never silently removed.

packages

object[]

required

One to thirty packages; all recognized registries, no silent row removal.

Required array length: 1 - 30 elements

Show child attributes

min_severity

null | enum<string>

Optional minimum for direct and transitive security; low=0.1, medium=4, high=7, critical=9. Null/omission includes unknown scores.

Available options:

low,

medium,

high,

critical

Response

Ordered reviews including partially unavailable packages

Atomic batch evidence; null values mean unavailable.

reviews

object[]

required

Source reviews.

Show child attributes

total

integer

required

Validated count of ordered input reviews, including unavailable reviews.

Required range: x >= 0

⌘I

Review package upgrades

curl --request POST \
  --url https://api.githits.dev/v1/package-upgrade-reviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "packages": [
    {
      "current_version": "1.0.0",
      "name": "example",
      "registry": "npm",
      "target_version": "2.0.0"
    }
  ]
}
'

import requests

url = "https://api.githits.dev/v1/package-upgrade-reviews"

payload = { "packages": [
        {
            "current_version": "1.0.0",
            "name": "example",
            "registry": "npm",
            "target_version": "2.0.0"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    packages: [
      {
        current_version: '1.0.0',
        name: 'example',
        registry: 'npm',
        target_version: '2.0.0'
      }
    ]
  })
};

fetch('https://api.githits.dev/v1/package-upgrade-reviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.githits.dev/v1/package-upgrade-reviews",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'packages' => [
        [
                'current_version' => '1.0.0',
                'name' => 'example',
                'registry' => 'npm',
                'target_version' => '2.0.0'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.githits.dev/v1/package-upgrade-reviews"

	payload := strings.NewReader("{\n  \"packages\": [\n    {\n      \"current_version\": \"1.0.0\",\n      \"name\": \"example\",\n      \"registry\": \"npm\",\n      \"target_version\": \"2.0.0\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.githits.dev/v1/package-upgrade-reviews")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"packages\": [\n    {\n      \"current_version\": \"1.0.0\",\n      \"name\": \"example\",\n      \"registry\": \"npm\",\n      \"target_version\": \"2.0.0\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.githits.dev/v1/package-upgrade-reviews")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"packages\": [\n    {\n      \"current_version\": \"1.0.0\",\n      \"name\": \"example\",\n      \"registry\": \"npm\",\n      \"target_version\": \"2.0.0\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "reviews": [
    {
      "changelog": {
        "breaking_signals": [],
        "entries": [
          {
            "body": "Release notes",
            "body_preview": "Release notes",
            "detail_source": "releases",
            "has_changelog": true,
            "headline": "Release",
            "html_url": null,
            "published_at": null,
            "signals": [],
            "source_version": "v2.0.0",
            "version": "2.0.0"
          }
        ],
        "fallback": null,
        "has_release_note_bodies": true,
        "keyword_entries": [],
        "migration_signals": [],
        "source": "releases",
        "total_entries": 1,
        "total_entries_with_bodies": 1,
        "total_keyword_entries": 0,
        "truncated": false
      },
      "compatibility": {
        "notes": [],
        "peer_dependency_changes": []
      },
      "current_version": "1.0.0",
      "dependency_changes": {
        "direct": {
          "added": [],
          "changed": [],
          "removed": []
        },
        "transitive": {
          "added": [],
          "changed": [],
          "removed": []
        }
      },
      "dependency_issues": {
        "current_total": 0,
        "introduced_conflicts": [],
        "introduced_deprecated": [],
        "introduced_duplicates": [],
        "introduced_outdated": [],
        "target_total": 0
      },
      "name": "example",
      "registry": "npm",
      "security": {
        "current": {
          "advisories": [],
          "affected_count": 0,
          "all_count": 0,
          "deprecated": false,
          "deprecation_reason": null,
          "last_modified_at": null,
          "non_affecting_count": 0,
          "published_at": null,
          "version": "1.0.0"
        },
        "fixed": [],
        "introduced": [],
        "target": {
          "advisories": [],
          "affected_count": 0,
          "all_count": 0,
          "deprecated": false,
          "deprecation_reason": null,
          "last_modified_at": null,
          "non_affecting_count": 0,
          "published_at": null,
          "version": "2.0.0"
        },
        "transitive": {
          "current_affected": 0,
          "fixed_package_details": {
            "entries": [],
            "total_count": 0,
            "truncated": false
          },
          "fixed_packages": [],
          "introduced_package_details": {
            "entries": [],
            "total_count": 0,
            "truncated": false
          },
          "introduced_packages": [],
          "still_affected_package_details": {
            "entries": [],
            "total_count": 0,
            "truncated": false
          },
          "target_affected": 0
        },
        "unchanged": []
      },
      "target_version": "2.0.0",
      "unknown_details": [],
      "version_delta": "major"
    }
  ],
  "total": 1
}

Get started

v1 reference

Review package upgrades

Selector catalogue

Authorizations

Headers

Query Parameters

Body

Response