Skip to main content
POST
Submit a lockfile analysis job

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name
string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version
string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent
string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID
string

Optional caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9_-]{1,64}$

Query Parameters

kind
enum<string>

Job kind. Provide sbom in this query parameter or the multipart body; at least one location is required. If both locations provide it, the body wins. Repeated values in this location are rejected.

Available options:
sbom
format
enum<string>
default:cyclonedx

Requested result format. A multipart format field overrides this value. Omit both locations to select cyclonedx. Repeated values in one location are rejected; unknown query fields are rejected. Accept does not select the result format. cyclonedx returns CycloneDX 1.7 JSON (application/vnd.cyclonedx+json); spdx returns SPDX 2.3 tag-value (text/spdx); text returns a human-readable report (text/plain). All outputs use UTF-8. Accept does not select the successful output format.

Available options:
cyclonedx,
spdx,
text

Body

multipart/form-data

Send multipart/form-data. The complete request, including multipart headers and boundaries, must fit within 8,000,000 bytes. Supply kind=sbom either as a query parameter or the multipart kind field; if both locations supply it, the body field wins. The selected format also accepts query or body values, with the body winning when both are present. Repeated values within one location and unknown fields are rejected.

files[]
file[]
required

Repeat the literal field name files[] once per file, with raw UTF-8 file contents rather than base64. Set each part's filename to its path relative to a common repository root, for example app/package.json and app/package-lock.json. Preserve directory structure so manifests can be associated with their lockfiles. Send 1–256 files, each at most 5,242,880 bytes. Each filename must be at most 1,024 UTF-8 bytes and must be relative, with no empty, dot (.) or parent (..) path segments, backslashes or control characters. Upload manifests and/or lockfiles supported by the GitHits inventory service; their contents are analyzed asynchronously.

Required array length: 1 - 256 elements
format
enum<string>
default:cyclonedx

Optional result format. This multipart value overrides the query parameter. Omit both to receive CycloneDX JSON; duplicate values in one location are rejected.

Available options:
cyclonedx,
spdx,
text
kind
enum<string>

Optional multipart job kind. At least one sbom value is required across this field and the query parameter; when both are present, this multipart value wins. Duplicate values in this location are rejected.

Available options:
sbom

Response

The upload was admitted and queued for asynchronous analysis.

events_url
string<uri-reference>
required

Canonical relative URL for the job's server-sent event stream.

Pattern: ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/events$
Example:

"/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events"

expires_at
string<date-time>
required

Time after which the job and its result are no longer available.

Example:

"2026-10-10T12:00:00Z"

id
string<uuid>
required

Opaque identifier for this analysis job.

Pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
Example:

"01900000-0000-7000-8000-000000000001"

result_url
string<uri-reference>
required

Canonical relative URL for retrieving the completed analysis document.

Pattern: ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/result$
Example:

"/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result"

state
enum<string>
required

Initial state when the accepted job is placed in the queue.

Available options:
queued
Example:

"queued"

status_url
string<uri-reference>
required

Canonical relative URL for the job status snapshot.

Pattern: ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
Example:

"/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001"