Get dependency licenses for a completed analysis
Retrieve a JSON license report for an analysis job you can access. Use the analysis id returned in the HTTP 202 submission response. The synchronous POST /v1/experimental/licenses response has no job ID; a component’s bom_ref cannot be used here.
The job must have been submitted with kind=sbom&format=cyclonedx. You do not need to parse a CycloneDX document to use this JSON report. An audit job or a job using SPDX/text output returns 409 INCOMPATIBLE_ANALYSIS; choose a compatible job or submit a new one with the required parameters.
Create and follow a job
Use a GitHits Bearer credential for an active account with required terms accepted. In these examples, /path/to/private-auth.conf is your own protected curl configuration containing header = "Authorization: Bearer <token>"; replace the placeholder privately and keep the file outside your repository.
curl --config /path/to/private-auth.conf \
--fail-with-body --silent --show-error \
--form 'files[]=@package.json;filename=package.json' \
--form 'files[]=@package-lock.json;filename=package-lock.json' \
--output job.json \
'https://api.githits.dev/v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx'
- Check for HTTP 202 and read
idfromjob.json. Keepexpires_atand the returned links. - Resolve
status_urlorevents_urlagainst the API server URL. Read status or consume the server-sent events untilstate=succeeded. The presence ofresult_urlalone does not mean the job is ready. Onstate=failed, inspect the job status’serrorcode before deciding whether to submit new work; a licenses read also returns 409ANALYSIS_FAILEDwithfailure_code. - Replace
{id}below with the submission response’sidand request the licenses view:
curl --config /path/to/private-auth.conf \
--fail-with-body --silent --show-error \
--output licenses.json \
'https://api.githits.dev/v1/experimental/licenses/{id}'
On HTTP 200, licenses.json contains schema_version, inventory and components. On an HTTP error, curl exits unsuccessfully and saves a JSON problem in that file; check the exit status before treating it as a report. No query parameters or Accept-based format selection are supported.
Reading this report consumes zero analysis units. A new job reserves units from the monthly analysis allowance. The x-githits-cost value for this read is 0. Keep using the same ID for reads until the job expires.
Interpret the response
Every reported project, dependency or file/source entry remains separate, including repeated names, versions or package URLs. Use bom_ref for reported relationships and properties for input paths. licenses gives license choices; observed_licenses gives independent observations. publisher_evidence retains original publisher statements and release/package/repository context. source_evidence retains source-file paths, detected licenses and observation/attempt history. Both evidence fields are JSON objects already. Some named properties[].value strings contain extra JSON that you parse separately; the field descriptions identify them.
Null means the corresponding information was unavailable. Empty arrays do not prove that no license exists, that all files were checked, or that the dependency graph is complete. Read inventory.completeness with the component list. Dependency coverage is in inventory.compositions and the inventory.properties entry named githits:dependency_coverage; parse that entry’s value as JSON. Notices are properties named githits:notice. No chosen license, AND/OR relationship between separate choices, or pass/fail decision is added. New string values and fields can appear; preserve or ignore unfamiliar data instead of rejecting an otherwise usable report.
Handle errors
Problems use application/problem+json; branch on code and keep X-Request-ID for support.
| Status / code | What to do |
|---|---|
400 VALIDATION_ERROR / INVALID_SESSION_ID | Remove query parameters or correct the session header/field identified in detail. |
| 401 / 403 | Check the credential, account access and required terms; use any provided terms/acceptance links. |
404 ANALYSIS_NOT_FOUND | Check the submission ID and credential. Missing, expired and inaccessible jobs have the same response. A result that is no longer stored requires a new submission if you still need it. |
409 ANALYSIS_PENDING | Wait for completion through status/events, then retry this GET; do not submit a second job just to wait. |
409 ANALYSIS_FAILED | Inspect failure_code and the job status. Correct the input or cause before deliberately creating another analysis. |
409 INCOMPATIBLE_ANALYSIS | Use a job created with kind=sbom&format=cyclonedx; the format of an existing job cannot be changed by this GET. |
422 LICENSE_REPORT_TOO_LARGE | The JSON report exceeds 16,777,216 bytes. Download the job’s original CycloneDX document through result_url, or create a smaller analysis if appropriate. Jobs do not raise the report-size limit. |
429 RATE_LIMITED | Respect Retry-After when provided. |
502 UPSTREAM_ERROR | The analysis result could not be read. Keep the job ID and X-Request-ID, and report a persistent failure; do not repeatedly resubmit the same files. |
| 503 / 504 | Try reading the same job again later. This does not start another analysis. |
Responses must not be cached (Cache-Control: no-store). The report does not certify an installed artifact or complete license coverage.
curl --request GET \
--url https://api.githits.dev/v1/experimental/licenses/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.githits.dev/v1/experimental/licenses/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.githits.dev/v1/experimental/licenses/{id}', 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/experimental/licenses/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.githits.dev/v1/experimental/licenses/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.githits.dev/v1/experimental/licenses/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.githits.dev/v1/experimental/licenses/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"components": [
{
"bom_ref": "root",
"external_references": [],
"hashes": [],
"licenses": [
{
"acknowledgement": "declared",
"expression": "MIT"
}
],
"name": "project",
"observed_licenses": [],
"properties": [
{
"name": "githits:record_kind",
"value": "manifest"
},
{
"name": "githits:manifest_path",
"value": "package.json"
}
],
"publisher_evidence": null,
"purl": null,
"record_kind": "manifest",
"scope": null,
"source_evidence": null,
"type": "library",
"version": null
},
{
"bom_ref": "a",
"external_references": [
{
"hashes": [
{
"alg": "SHA-256",
"content": "reference-digest"
}
],
"type": "vcs",
"url": "https://example.com/source"
},
{
"type": "distribution",
"url": "https://example.com/artifact.tgz"
}
],
"hashes": [
{
"alg": "SHA-256",
"content": "package-digest"
}
],
"licenses": [
{
"acknowledgement": "declared",
"expression": "MIT",
"future_choice": true
},
{
"license": {
"name": "Opaque publisher terms"
}
}
],
"name": "dependency",
"observed_licenses": [],
"properties": [
{
"name": "githits:record_kind",
"value": "locked_package"
},
{
"name": "githits:lockfile_path",
"value": "one/package-lock.json"
},
{
"name": "githits:license_artifact_verification",
"value": "not_checked"
}
],
"publisher_evidence": {
"capture_status": "present",
"controlling_index": 0,
"coverage": "complete",
"display_value": "MIT",
"expression": "MIT",
"observations": [
{
"interpretation": {
"expression": "MIT",
"interpretation_methods": [
"spdx_expression"
],
"issues": [],
"status": "expression",
"syntax": "spdx"
},
"observation": {
"field": "license",
"relation": "single",
"scope": "release",
"source": "npm_registry",
"statements": [
"MIT"
],
"status": "present",
"version": "1.0.0"
},
"relationship": "controlling"
}
],
"reason": "publisher_release_metadata",
"status": "expression"
},
"purl": "pkg:npm/dependency@1.0.0",
"record_kind": "locked_package",
"scope": "excluded",
"source_evidence": null,
"type": "library",
"version": "1.0.0"
},
{
"bom_ref": "b",
"external_references": [
{
"hashes": [
{
"alg": "SHA-256",
"content": "reference-digest"
}
],
"type": "vcs",
"url": "https://example.com/source"
},
{
"type": "distribution",
"url": "https://example.com/artifact.tgz"
}
],
"hashes": [
{
"alg": "SHA-256",
"content": "package-digest"
}
],
"licenses": [
{
"acknowledgement": "declared",
"expression": "MIT",
"future_choice": true
},
{
"license": {
"name": "Opaque publisher terms"
}
}
],
"name": "dependency",
"observed_licenses": [],
"properties": [
{
"name": "githits:record_kind",
"value": "locked_package"
},
{
"name": "githits:lockfile_path",
"value": "two/package-lock.json"
},
{
"name": "githits:license_artifact_verification",
"value": "not_checked"
}
],
"publisher_evidence": {
"capture_status": "present",
"controlling_index": 0,
"coverage": "complete",
"display_value": "MIT",
"expression": "MIT",
"observations": [
{
"interpretation": {
"expression": "MIT",
"interpretation_methods": [
"spdx_expression"
],
"issues": [],
"status": "expression",
"syntax": "spdx"
},
"observation": {
"field": "license",
"relation": "single",
"scope": "release",
"source": "npm_registry",
"statements": [
"MIT"
],
"status": "present",
"version": "1.0.0"
},
"relationship": "controlling"
}
],
"reason": "publisher_release_metadata",
"status": "expression"
},
"purl": "pkg:npm/dependency@1.0.0",
"record_kind": "locked_package",
"scope": "excluded",
"source_evidence": null,
"type": "library",
"version": "1.0.0"
},
{
"bom_ref": "go",
"external_references": [],
"hashes": [],
"licenses": [],
"name": "example.com/source",
"observed_licenses": [
{
"license": {
"name": "Apache-2.0"
}
},
{
"license": {
"name": "MIT"
}
}
],
"properties": [
{
"name": "githits:record_kind",
"value": "resolved_package"
},
{
"name": "githits:manifest_path",
"value": "go.mod"
}
],
"publisher_evidence": null,
"purl": "pkg:golang/example.com/source@v1.0.0",
"record_kind": "resolved_package",
"scope": null,
"source_evidence": {
"checked_at": "2026-10-22T12:00:00Z",
"files": [
{
"detected_licenses": [
"Apache-2.0"
],
"path": "LICENSE"
},
{
"detected_licenses": [
"MIT"
],
"path": "nested/LICENSE"
}
],
"last_attempt_at": "2026-10-22T12:00:00Z",
"last_attempt_status": "ambiguous",
"method": "licensecheck",
"module": "example.com/source",
"provider": "pkg_go_dev",
"status": "ambiguous",
"url": "https://pkg.go.dev/example.com/source@v1.0.0?tab=licenses",
"version": "v1.0.0"
},
"type": "library",
"version": "v1.0.0"
},
{
"bom_ref": "file",
"external_references": [],
"hashes": [],
"licenses": [],
"name": "local subject",
"observed_licenses": [],
"properties": [],
"publisher_evidence": null,
"purl": null,
"record_kind": null,
"scope": null,
"source_evidence": null,
"type": "file",
"version": null
}
],
"inventory": {
"completeness": "recorded_lockfile_inventory",
"compositions": [
{
"aggregate": "unknown",
"assemblies": [
"root",
"a",
"b",
"go",
"file"
]
}
],
"dependencies": [
{
"dependsOn": [
"a"
],
"ref": "root"
},
{
"dependsOn": [
"b"
],
"ref": "a"
}
],
"properties": [
{
"name": "githits:completeness",
"value": "recorded_lockfile_inventory"
},
{
"name": "githits:notice",
"value": "License metadata and connectivity may be incomplete."
},
{
"name": "githits:resolutions",
"value": "[{\"path\":\"package.json\",\"status\":\"partial\"}]"
}
]
},
"schema_version": 1
}Authorizations
Headers
Optional caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created.
1 - 64^[A-Za-z0-9_-]{1,64}$Path Parameters
Analysis id returned in the HTTP 202 JSON response from POST /v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx. Use a credential that can access that job, such as the credential used to submit it. A component bom_ref is not a job id. Missing, malformed, expired or inaccessible ids return ANALYSIS_NOT_FOUND after authentication.
Response
JSON license report, at most 16,777,216 bytes. Read inventory coverage and component evidence together; a successful response may be partial and does not provide a pass/fail decision.
JSON license inventory with separate license choices, publisher statements and source-file observations, plus input attribution and coverage. It provides evidence for your own evaluation rather than an allow/deny result. Additional fields can appear.
curl --request GET \
--url https://api.githits.dev/v1/experimental/licenses/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.githits.dev/v1/experimental/licenses/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.githits.dev/v1/experimental/licenses/{id}', 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/experimental/licenses/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.githits.dev/v1/experimental/licenses/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.githits.dev/v1/experimental/licenses/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.githits.dev/v1/experimental/licenses/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"components": [
{
"bom_ref": "root",
"external_references": [],
"hashes": [],
"licenses": [
{
"acknowledgement": "declared",
"expression": "MIT"
}
],
"name": "project",
"observed_licenses": [],
"properties": [
{
"name": "githits:record_kind",
"value": "manifest"
},
{
"name": "githits:manifest_path",
"value": "package.json"
}
],
"publisher_evidence": null,
"purl": null,
"record_kind": "manifest",
"scope": null,
"source_evidence": null,
"type": "library",
"version": null
},
{
"bom_ref": "a",
"external_references": [
{
"hashes": [
{
"alg": "SHA-256",
"content": "reference-digest"
}
],
"type": "vcs",
"url": "https://example.com/source"
},
{
"type": "distribution",
"url": "https://example.com/artifact.tgz"
}
],
"hashes": [
{
"alg": "SHA-256",
"content": "package-digest"
}
],
"licenses": [
{
"acknowledgement": "declared",
"expression": "MIT",
"future_choice": true
},
{
"license": {
"name": "Opaque publisher terms"
}
}
],
"name": "dependency",
"observed_licenses": [],
"properties": [
{
"name": "githits:record_kind",
"value": "locked_package"
},
{
"name": "githits:lockfile_path",
"value": "one/package-lock.json"
},
{
"name": "githits:license_artifact_verification",
"value": "not_checked"
}
],
"publisher_evidence": {
"capture_status": "present",
"controlling_index": 0,
"coverage": "complete",
"display_value": "MIT",
"expression": "MIT",
"observations": [
{
"interpretation": {
"expression": "MIT",
"interpretation_methods": [
"spdx_expression"
],
"issues": [],
"status": "expression",
"syntax": "spdx"
},
"observation": {
"field": "license",
"relation": "single",
"scope": "release",
"source": "npm_registry",
"statements": [
"MIT"
],
"status": "present",
"version": "1.0.0"
},
"relationship": "controlling"
}
],
"reason": "publisher_release_metadata",
"status": "expression"
},
"purl": "pkg:npm/dependency@1.0.0",
"record_kind": "locked_package",
"scope": "excluded",
"source_evidence": null,
"type": "library",
"version": "1.0.0"
},
{
"bom_ref": "b",
"external_references": [
{
"hashes": [
{
"alg": "SHA-256",
"content": "reference-digest"
}
],
"type": "vcs",
"url": "https://example.com/source"
},
{
"type": "distribution",
"url": "https://example.com/artifact.tgz"
}
],
"hashes": [
{
"alg": "SHA-256",
"content": "package-digest"
}
],
"licenses": [
{
"acknowledgement": "declared",
"expression": "MIT",
"future_choice": true
},
{
"license": {
"name": "Opaque publisher terms"
}
}
],
"name": "dependency",
"observed_licenses": [],
"properties": [
{
"name": "githits:record_kind",
"value": "locked_package"
},
{
"name": "githits:lockfile_path",
"value": "two/package-lock.json"
},
{
"name": "githits:license_artifact_verification",
"value": "not_checked"
}
],
"publisher_evidence": {
"capture_status": "present",
"controlling_index": 0,
"coverage": "complete",
"display_value": "MIT",
"expression": "MIT",
"observations": [
{
"interpretation": {
"expression": "MIT",
"interpretation_methods": [
"spdx_expression"
],
"issues": [],
"status": "expression",
"syntax": "spdx"
},
"observation": {
"field": "license",
"relation": "single",
"scope": "release",
"source": "npm_registry",
"statements": [
"MIT"
],
"status": "present",
"version": "1.0.0"
},
"relationship": "controlling"
}
],
"reason": "publisher_release_metadata",
"status": "expression"
},
"purl": "pkg:npm/dependency@1.0.0",
"record_kind": "locked_package",
"scope": "excluded",
"source_evidence": null,
"type": "library",
"version": "1.0.0"
},
{
"bom_ref": "go",
"external_references": [],
"hashes": [],
"licenses": [],
"name": "example.com/source",
"observed_licenses": [
{
"license": {
"name": "Apache-2.0"
}
},
{
"license": {
"name": "MIT"
}
}
],
"properties": [
{
"name": "githits:record_kind",
"value": "resolved_package"
},
{
"name": "githits:manifest_path",
"value": "go.mod"
}
],
"publisher_evidence": null,
"purl": "pkg:golang/example.com/source@v1.0.0",
"record_kind": "resolved_package",
"scope": null,
"source_evidence": {
"checked_at": "2026-10-22T12:00:00Z",
"files": [
{
"detected_licenses": [
"Apache-2.0"
],
"path": "LICENSE"
},
{
"detected_licenses": [
"MIT"
],
"path": "nested/LICENSE"
}
],
"last_attempt_at": "2026-10-22T12:00:00Z",
"last_attempt_status": "ambiguous",
"method": "licensecheck",
"module": "example.com/source",
"provider": "pkg_go_dev",
"status": "ambiguous",
"url": "https://pkg.go.dev/example.com/source@v1.0.0?tab=licenses",
"version": "v1.0.0"
},
"type": "library",
"version": "v1.0.0"
},
{
"bom_ref": "file",
"external_references": [],
"hashes": [],
"licenses": [],
"name": "local subject",
"observed_licenses": [],
"properties": [],
"publisher_evidence": null,
"purl": null,
"record_kind": null,
"scope": null,
"source_evidence": null,
"type": "file",
"version": null
}
],
"inventory": {
"completeness": "recorded_lockfile_inventory",
"compositions": [
{
"aggregate": "unknown",
"assemblies": [
"root",
"a",
"b",
"go",
"file"
]
}
],
"dependencies": [
{
"dependsOn": [
"a"
],
"ref": "root"
},
{
"dependsOn": [
"b"
],
"ref": "a"
}
],
"properties": [
{
"name": "githits:completeness",
"value": "recorded_lockfile_inventory"
},
{
"name": "githits:notice",
"value": "License metadata and connectivity may be incomplete."
},
{
"name": "githits:resolutions",
"value": "[{\"path\":\"package.json\",\"status\":\"partial\"}]"
}
]
},
"schema_version": 1
}