Skip to main content
Use the experimental REST API to upload manifests and lockfiles, generate a dependency inventory, or audit the recorded dependencies. Use a bearer token 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

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

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

For an asynchronous SBOM, use kind=sbom and format=cyclonedx, spdx, or text. The 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

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