> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SBOM, audit and licenses

> Upload manifests and lockfiles to generate SBOMs, audit dependencies and read compact license reports through the experimental REST API.

Upload your manifests and lockfiles to an asynchronous analysis job, then retrieve an SBOM, dependency audit findings or a compact license report through the REST API.

> [!TIP]
>
> To run these analyses from a repository or CI, use [Scan (`githits-scan`)](https://docs.githits.com/scan/overview).

> [!NOTE]
>
> These operations are experimental and pre-production. The [v1 contract](https://docs.githits.com/api/versioning.md) is not finalized; routes and report schemas can change.

## Choose an operation

Submit to `POST /v1/experimental/lockfile-jobs` with the query parameters below. Each submission returns HTTP `202` with a job ID and progress URLs.

| Operation | Submit query | After submission |
| - | - | - |
| Generate an SBOM | `kind=sbom`, `format=cyclonedx` (or `spdx`, `text`) | Follow `events_url` until success, then download `result_url` |
| Audit dependencies | `kind=audit`, `format=json` | Follow `events_url` until success, then download JSON from `result_url` |
| Read a license report | `kind=sbom`, `format=cyclonedx` | Follow `events_url` until success, then read `GET /v1/experimental/license-reports/{id}` |

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](https://docs.githits.com/api/authentication.md) 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 multipart `files[]` 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](https://docs.githits.com/api-reference/v1/experimental/generate-an-sbom-from-uploaded-files.md) 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.

| Upload limit | Value |
| - | - |
| Files per request | 1–256 |
| Bytes per file | At most 5,242,880 |
| Complete multipart body, including framing | At most 8,000,000 bytes |
| Filename length | At most 1,024 UTF-8 bytes |

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](https://docs.githits.com/api-reference/v1/experimental/submit-a-lockfile-analysis-job.md) for admission rules.

## Submit an SBOM job

This example uploads a Cargo manifest and lockfile and requests CycloneDX JSON:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  --form 'files[]=@Cargo.toml;filename=Cargo.toml' \
  --form 'files[]=@Cargo.lock;filename=Cargo.lock' \
  --output job.json \
  'https://api.githits.dev/v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx'
```

Choose the format at submission; `Accept` does not select it:

| `format` | Download |
| - | - |
| `cyclonedx` (default) | CycloneDX 1.7 JSON; save as `bom.cdx.json` |
| `spdx` | SPDX 2.3 tag-value, not JSON; save as `bom.spdx` |
| `text` | Human-readable inventory report; save as `bom.txt` |

## Submit an audit job

Audit uses the same job route with `kind=audit&format=json`. This example uploads a Python uv lockfile:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  --form 'files[]=@uv.lock;filename=uv.lock' \
  --output job.json \
  'https://api.githits.dev/v1/experimental/lockfile-jobs?kind=audit&format=json'
```

For either submission, check curl's exit status before using `job.json`. With `--fail-with-body`, an HTTP failure saves a problem response there. A successful [submission response](https://docs.githits.com/api-reference/v1/experimental/submit-a-lockfile-analysis-job.md) 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 returned `events_url` with bearer authentication. `--no-buffer` displays server-sent events as they arrive:

```bash theme={null}
EVENTS_URL=$(jq -r '.events_url' job.json)
curl --fail-with-body --silent --show-error --no-buffer \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  --header 'Accept: text/event-stream' \
  "https://api.githits.dev$EVENTS_URL"
```

Apply each `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](https://docs.githits.com/api-reference/v1/experimental/stream-lockfile-analysis-progress.md).

You can also read the returned `status_url` for the [latest status](https://docs.githits.com/api-reference/v1/experimental/get-lockfile-analysis-status.md):

```bash theme={null}
STATUS_URL=$(jq -r '.status_url' job.json)
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  "https://api.githits.dev$STATUS_URL"
```

Only after `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.

```bash theme={null}
RESULT_URL=$(jq -r '.result_url' job.json)
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  --output bom.cdx.json \
  "https://api.githits.dev$RESULT_URL"
```

Check curl's exit status before consuming the file: an HTTP failure saves a problem response instead of the result. Successful downloads contain the document directly, without a JSON wrapper.

The [result endpoint](https://docs.githits.com/api-reference/v1/experimental/download-a-completed-lockfile-analysis.md) returns `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](#submit-an-sbom-job) with `kind=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.

```bash theme={null}
JOB_ID=$(jq -r '.id' job.json)
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  --output license-report.json \
  "https://api.githits.dev/v1/experimental/license-reports/$JOB_ID"
```

The successful response is the compact JSON report with `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](https://api.githits.dev/v1/openapi.json) 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 contains `schema_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

Synchronous `POST /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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.