These operations are experimental and pre-production. The v1 contract is not finalized; routes and report schemas can change.
Choose an operation
Submit toPOST /v1/experimental/lockfile-jobs with the query parameters below. Each submission returns HTTP 202 with a job ID and progress URLs.
Follow the event stream for progress, or read the returned
status_url for the latest snapshot. For license reports, use the job ID to read the compact report instead of downloading the SBOM result.
Use a bearer token for an active account with the required terms accepted. The examples expect GITHITS_API_TOKEN in your environment, curl and jq. Supply the token through your secret store and keep shell tracing disabled. Run from your repository root and substitute your own files. Choose one submission below; each saves its response as job.json for the follow-up commands.
Prepare files
Send individual UTF-8 files as repeated multipartfiles[] parts, with raw contents rather than base64, archives or a repository URL. Preserve paths relative to a common repository root, such as app/package.json and app/package-lock.json. Let curl set the multipart content type and boundary.
Supported inputs include Cargo, npm/pnpm/Yarn classic and Berry, uv/Poetry/PDM/Pipenv, Go go.mod, Swift, Gradle, NuGet, Dart, Composer, Mix, Bundler, Rebar, Conan and Go dep. This list is non-exhaustive; recognition depends on filenames and contents. See the upload and format reference for details.
go.sum and requirements.txt are unsupported: do not upload them as companion files. One unusable file rejects the entire upload with 422 UNUSABLE_MANIFEST; companion files are not silently ignored. Lockfiles can be submitted alone.
Filenames must be relative and cannot contain backslashes, empty segments,
. or .. segments, or control characters. Preserve directory structure so manifests can be associated with lockfiles. A nested manifest does not automatically inherit an ancestor lockfile.
Analysis submissions consume quota. The current default reserves 100 daily units per analysis; failures after admission do not necessarily refund them. A new submission can consume quota again. Status reads, progress connections and result reads, including compact license reports, do not resubmit the analysis or reserve another 100 units. Handle 429 using Retry-After when supplied. See the submission reference for admission rules.
Submit an SBOM job
This example uploads a Cargo manifest and lockfile and requests CycloneDX JSON:Accept does not select it:
Submit an audit job
Audit uses the same job route withkind=audit&format=json. This example uploads a Python uv lockfile:
job.json. With --fail-with-body, an HTTP failure saves a problem response there. A successful submission response includes id, state, expires_at, status_url, events_url and result_url. Retain these values. The URLs are relative to https://api.githits.dev.
Follow progress and download
Stream the returnedevents_url with bearer authentication. --no-buffer displays server-sent events as they arrive:
snapshot event as a complete state replacement. Revisions are nondecreasing but can repeat: state or attempt can change at the same revision. If the stream closes before a terminal snapshot, reconnect to the same URL for the latest snapshot, not historical replay. Stop streaming and reconnecting when state is succeeded or failed. Disconnecting does not cancel the job. See the progress reference.
You can also read the returned status_url for the latest status:
state is succeeded, download the SBOM or audit result before expires_at. This example saves CycloneDX; use audit.json, bom.spdx or bom.txt for the other outputs. For a license report, skip this download and use the next section.
409 ANALYSIS_PENDING while work continues and 409 ANALYSIS_FAILED for a failed job. A result_url is present even before the result is ready. Unknown, expired and inaccessible jobs return 404 ANALYSIS_NOT_FOUND after authentication. Retain the job ID and read its status after a timeout instead of automatically submitting again.
Read a compact license report
Submit the SBOM job above withkind=sbom&format=cyclonedx, then follow its events until state is succeeded. Use that submission’s id to read the compact license report. Do not download result_url for this flow.
schema_version: 2. This read uses the existing analysis, with the same authorization and expiry; it does not start another analysis. Check curl’s exit status before consuming the report file.
This endpoint requires a finished CycloneDX SBOM job. Audit, SPDX and text jobs return 409 INCOMPATIBLE_ANALYSIS; pending and failed jobs return 409 ANALYSIS_PENDING and 409 ANALYSIS_FAILED. Use the submission’s job ID, not a component’s bom_ref.
The OpenAPI definition documents GET /v1/experimental/license-reports/{id} under Preview a compact report for a completed analysis (get_compact_dependency_licenses).
Interpret results
A successful analysis can still describe a partial inventory. Inspect completeness and per-manifest resolution information. Compatible lockfiles supply recorded versions; uncovered manifests resolve separately. GitHits does not verify that a lockfile is up to date, and an SBOM does not guarantee an exact installed inventory. Audit JSON contains findings and independent coverage information. Inspect both: no findings does not prove that every dependency was assessed. The compact license report containsschema_version, inventory input and coverage context, and components with license evidence, not a policy verdict or certification. Keep reported license choices, publisher context and source-file observations distinct. Inspect inventory and license coverage separately; missing licenses or empty choices mean unavailable information, not that no license applies or every file was checked. A successful response does not certify installed artifacts or complete license coverage.
Also available
SynchronousPOST /v1/experimental/sbom, POST /v1/experimental/licenses and POST /v1/experimental/license-reports are not recommended and are likely to be removed. The legacy GET /v1/experimental/licenses/{id} returns schema 1; use the compact schema-2 read above for new integrations.