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 or audit 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. Supported request job kinds; response vocabulary remains open.

Available options:
sbom,
audit
format
enum<string>

Requested result format. A multipart format field overrides this value. Omit both locations to select cyclonedx for sbom or json for audit. Only sbom with cyclonedx/spdx/text and audit with json are admitted. Repeated values in one location are rejected; unknown query fields are rejected. Accept does not select the result format. Closed request formats. SBOM accepts cyclonedx/spdx/text; audit accepts only json. Omission chooses the kind-specific default.

Available options:
cyclonedx,
spdx,
text,
json
report_version
enum<string>

Audit only: opt into native lifecycle with 3. Omission or 2 preserves v2. Multipart text overrides this query value; duplicates and unsupported values are rejected. Dispatch on the returned schema_version, including a possible v2 response to a v3 request.

Available options:
2,
3

Body

multipart/form-data

Send multipart/form-data. The complete request, including multipart headers and boundaries, must fit within 8,000,000 bytes. Supply a required kind of sbom or audit either as a query parameter or the multipart kind field; if both locations supply kind, the body field wins. SBOM jobs accept cyclonedx, spdx, or text and default to cyclonedx; audit jobs accept json and default to json. Crossed kind/format pairs are rejected. 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. Audit alone accepts optional report_version=2 or 3 in query or multipart text; the body wins. Omission preserves v2. Clients inspect returned schema_version; older workers can return v2 even when v3 was requested.

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>

Optional result format. SBOM accepts cyclonedx, spdx, or text and defaults to cyclonedx; audit accepts json and defaults to json. This multipart value overrides the query parameter. Crossed kind and format pairs are rejected. Duplicate values in one location are rejected.

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

Required across the query and multipart body; accepted values are sbom and audit. When both locations supply kind, this multipart value wins. Duplicate values in this location are rejected.

Available options:
sbom,
audit
report_version
enum<string>

Audit jobs only. Select native lifecycle report 3 explicitly; omission or 2 preserves released v2. Body overrides the query. Duplicate values in one location and non-audit use are rejected.

Available options:
2,
3

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
string
required

Initial state when the accepted job is placed in the queue. Open response vocabulary; clients must accept unfamiliar values and codes.

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"