Experimental

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 id from job.json. Keep expires_at and the returned links.
Resolve status_url or events_url against the API server URL. Read status or consume the server-sent events until state=succeeded. The presence of result_url alone does not mean the job is ready. On state=failed, inspect the job status’s error code before deciding whether to submit new work; a licenses read also returns 409 ANALYSIS_FAILED with failure_code.
Replace {id} below with the submission response’s id and 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 does not start another analysis or reserve another set of analysis units. Submitting a new job is a new analysis (currently 100 weighted daily units at default policy). The x-githits-cost value for this read is 0. Keep using the same ID for reads until the job expires instead of resubmitting just to retrieve the report.

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.

GET

experimental

licenses

{id}

Get dependency licenses for a completed analysis

curl --request GET \
  --url https://api.githits.dev/v1/experimental/licenses/{id} \
  --header 'Authorization: Bearer <token>'

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))

}

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

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 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.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]{1,64}$

Path Parameters

string

required

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.

components

object[]

required

All reported occurrences in their original order, with the selected primary project/source entry first when one exists. Keep repeated names, versions and package URLs separate; use bom_ref and input-path properties for attribution.

Show child attributes

inventory

object

required

Input provenance, inventory coverage and reported dependency relationships. Read these facts alongside the component list; successful analysis can still be partial.

Show child attributes

schema_version

enum<integer>

required

Version of this JSON report structure, currently 1.

Available options:

1

⌘I

Get dependency licenses for a completed analysis

curl --request GET \
  --url https://api.githits.dev/v1/experimental/licenses/{id} \
  --header 'Authorization: Bearer <token>'

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))

}

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
}

Get started

v1 reference

Get dependency licenses for a completed analysis

Authorizations

Headers

Path Parameters

Response