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

# Analyze manifests and lockfiles

> Generate an SBOM or run an asynchronous dependency audit through the experimental GitHits REST API.

Use the experimental REST API to upload manifests and lockfiles, generate a dependency inventory, or audit the recorded dependencies.

Use a [bearer token](/api/authentication.md) for an active account with the required terms accepted. The examples expect `GITHITS_API_TOKEN` in your environment and npm files in your current directory. Substitute the files for your project.

## Choose an operation

| Task | Request | Result |
| - | - | - |
| Generate an SBOM in one request | `POST /v1/experimental/sbom` | HTTP `200` with the document |
| Generate an SBOM with progress and later download | `POST /v1/experimental/lockfile-jobs`, `kind=sbom` | HTTP `202` with job URLs |
| Audit dependencies with progress and later download | `POST /v1/experimental/lockfile-jobs`, `kind=audit` | HTTP `202` with job URLs |

SBOM output supports `cyclonedx` (default, CycloneDX 1.7 JSON), `spdx` (SPDX 2.3 tag-value), and `text`. Audit output uses `json`. Choose the format at submission; the `Accept` header does not select it.

## Prepare files

Send individual UTF-8 files as repeated multipart `files[]` parts. 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 npm manifests and lockfiles, Cargo, and other ecosystems listed in the [SBOM reference](/api-reference/v1/experimental/generate-an-sbom-from-uploaded-files.md). `go.sum` and `requirements.txt` are unsupported. One unusable file rejects the entire upload; companion files are not silently ignored. Lockfiles can be submitted alone.

Upload 1–256 files, each at most 5,242,880 bytes, within an 8,000,000-byte multipart body including framing. Filenames must be relative and cannot contain backslashes, empty segments, `.` or `..` segments, or control characters.

Analysis submissions consume quota. The current default reserves 100 daily units per analysis, and failures after admission do not necessarily refund them. Repeated submissions can consume quota again. See the reference for current admission rules and limits, and handle `429` using `Retry-After` when supplied.

## Generate an SBOM

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

Check cURL's exit status before importing the output. On HTTP failure, `--fail-with-body` saves a problem response in the same file. Successful responses contain the document directly, without a JSON wrapper. Save it: this synchronous operation provides no later retrieval URL.

A successful document can still describe a partial inventory. Inspect completeness and per-manifest resolution information; an SBOM does not guarantee an exact installed inventory or complete license information. A compatible lockfile supplies recorded versions, while uncovered manifests resolve separately. GitHits does not verify that a lockfile is up to date.

## Submit an audit job

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

For an asynchronous SBOM, use `kind=sbom` and `format=cyclonedx`, `spdx`, or `text`. The [submission response](/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

1. Send an authenticated GET to the returned `status_url`, or stream the returned `events_url` using an HTTP client that supports bearer headers and server-sent events.
2. Apply each `snapshot` event as a complete state replacement. Revisions are nondecreasing but can repeat: state or attempt can change at the same revision. Reconnection gives the latest snapshot, not historical replay.
3. Stop streaming and reconnecting when the state is `succeeded` or `failed`. Disconnecting does not cancel the job.
4. Only when the state is `succeeded`, send an authenticated GET to `result_url` and save the response before `expires_at`. The URL exists even while the result is not ready.

The [result endpoint](/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. Unknown, expired, and inaccessible jobs return `404 ANALYSIS_NOT_FOUND` after authentication.

Audit JSON contains findings and independent coverage information. Inspect both: no findings does not prove that every dependency was assessed. Status reads, progress connections, and result retrieval do not submit another analysis. Prefer those operations to repeating a submission after a timeout.


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