Generate an SBOM from uploaded files

Generate a dependency inventory from manifest and lockfile uploads without creating a project. Manifest-only inputs resolve concrete versions and transitives. Compatible lockfiles supply recorded versions for associated manifests; uncovered manifests resolve separately.

First request

Use a GitHits Bearer credential for an active account with the required terms accepted. In the example, private-auth.conf is a caller-owned protected curl configuration containing header = "Authorization: Bearer <token>"; replace the placeholder privately. Run from your repository root:

curl --config /path/to/private-auth.conf \
  --fail-with-body --silent --show-error \
  --form 'files[]=@Cargo.toml;filename=Cargo.toml' \
  --form 'files[]=@Cargo.lock;filename=Cargo.lock' \
  --output bom.cdx.json \
  'https://api.githits.dev/v1/experimental/sbom?format=cyclonedx'

For npm, replace the two files with package.json and package-lock.json. For a nested project, use both the actual local path and the repository-relative filename, for example files[]=@app/package.json;filename=app/package.json. Repeat files[] for each file. Let curl set Content-Type and the multipart boundary. Send individual manifests and lockfiles, not an archive, repository URL or base64 data.

On success the output file contains the document itself. On an HTTP error, curl exits unsuccessfully and saves a JSON problem in that file; check the exit status before importing it as an SBOM.

Upload rules

Send repeated files[] parts with repository-relative filenames and raw UTF-8 contents. Keep directories intact, for example app/package.json and app/package-lock.json. Only files[] and optional format are accepted. The complete multipart body, including framing, is limited to 8,000,000 bytes: 1–256 files, each at most 5,242,880 bytes, with filenames at most 1,024 UTF-8 bytes. Empty, dot and parent path segments, backslashes and controls are invalid. Unknown fields, missing filenames and duplicate format values in one location are rejected. A malformed query format is invalid even when multipart supplies a format.

Supported manifest examples include Cargo.toml, package.json, pyproject.toml, Pipfile, go.mod, mix.exs and rebar.config. This list is non-exhaustive; support depends on the contents, not just the filename. go.sum and requirements.txt are unsupported: do not include them as companion files. One unusable file rejects the entire upload with 422 UNUSABLE_MANIFEST; companion files are not silently ignored.

Supported lockfile families include Cargo, npm, pnpm, Yarn classic and Berry, uv, Poetry, PDM, Pipenv, Swift, Gradle, NuGet, Dart, Composer, Mix, Bundler, Rebar, Conan and Go dep. Filename and contents determine recognition; renaming an unsupported file does not add support. Lockfiles can be uploaded alone. A compatible same-directory lockfile supplies recorded versions for its manifest; this does not verify that the lockfile is up to date. For monorepos, preserve all relative paths; a nested manifest does not automatically inherit an ancestor lockfile.

Choose an output

All outputs use UTF-8 and are limited to 16,777,216 bytes. Change the example’s query to ?format=spdx or ?format=text, or add --form 'format=spdx'; the multipart value wins. Accept does not select the format. Success returns HTTP 200 with the direct document, without a JSON wrapper or retrieval URL. No fields selector is supported.

Standard document fields retain their standard spelling. The response schema describes an extensible subset of CycloneDX 1.7, not a field allowlist: additional standard metadata, component, license, dependency and other fields are accepted at every object level. Clients must preserve or ignore unfamiliar fields. SPDX tag-value documents may likewise include additional standard fields.

Interpret the inventory

One unusable file rejects the upload. Incomplete resolution and missing licenses can still produce a successful partial document. License declarations are evidence, not legal conclusions or artifact verification. Lockfile agreement and platform conditions are not checked. Preserve completeness, provenance, license expression/name variants and optional PURLs when consuming the result.

In CycloneDX, find the document-level property named githits:completeness by name rather than array position:

None guarantees an exact installed inventory or complete license coverage. Inspect githits:resolutions and githits:manifest_associations for per-manifest evidence. Structured githits: property values are JSON encoded inside strings and require a separate decode. Component names are not unique; retain bom-ref for document relationships. A missing version, PURL or license means unavailable evidence, not permission to invent a value.

Analysis admission and cost

Synchronous SBOM and asynchronous SBOM/audit submissions share a backend analysis submission bucket. Current defaults allow 2 submissions per personal principal or 5 per organization/project principal in a first-hit fixed 60-second window; project credentials in the same organization share that principal. These are policy defaults, subject to runtime overrides. Backend admission is authoritative: handle 429 RATE_LIMITED and respect Retry-After when present.

At current policy defaults, a normally metered analysis reserves 100 weighted daily units from the same daily budget used by ordinary metered tool requests: one analysis costs as much as 100 ordinary metered calls. Both operation costs can be overridden by runtime policy. Gateway operation telemetry (githits.cost=1) is provisional and does not describe this backend debit. The short-rate bucket is checked before parsing. Normal daily admission reserves the 100 units after format/size preflight but before parsing; later parser, resolution or rendering failures do not refund the reservation. Unsupported companion files can therefore reject the entire upload after reservation.

Gateway-local validation rejections make no backend call and consume neither backend bucket. A backend 422 can follow reservation; transport or admission-authority failures can leave the charge unknown or unmetered. An error response alone proves neither a refund nor an exact debit. Avoid submitting the same analysis again unless you intend another admission.

Handle errors and retries

Errors use application/problem+json in every output format. Branch on code, not detail, and retain X-Request-ID for support. The response definitions below provide problem schemas and examples.

Uploads and documents are not retained for retrieval. Save the response. Repeated requests regenerate the document and consume request quota. Client upload has a 30-second deadline; the gateway allows 150 seconds for the upstream exchange, including the complete response read, in addition to upload time. A timeout does not guarantee processing stopped. Avoid unconditional retries: there is no idempotency key or saved result to resume.