Submit a lockfile analysis job
Submit uploaded manifests and lockfiles for asynchronous dependency analysis. Authenticate with a GitHits Bearer credential for an active account that has accepted the required terms. Supply kind=sbom or kind=audit either as a query parameter or multipart field; when both are supplied, the multipart field wins. Supply format in either location or both; the multipart field wins, and omission selects cyclonedx for sbom or json for audit. SBOM accepts cyclonedx/spdx/text; audit accepts only json. Crossed effective pairs are rejected before upstream admission. Audit additionally accepts report_version=2 or 3 as query or multipart text, with multipart precedence. Omission preserves v2; non-audit use and invalid/repeated controls are rejected before admission. Inspect returned schema_version, since an older worker may return v2 even when 3 was requested. Repeated values within one location and unknown query or multipart fields are rejected. The gateway reports one provisional operation. One monthly analysis unit is reserved at admission for an SBOM or audit job, charged on success, and released if the analysis fails. See POST /v1/experimental/sbom for input support, strict whole-upload rejection and shared submission limits. Reads, progress, reconnects and execution retries consume zero additional analysis units. This endpoint returns HTTP 202 when the job is queued. The existing /v1/experimental/sbom endpoint remains synchronous and returns an HTTP 200 document.
curl --request POST \
--url https://api.githits.dev/v1/experimental/lockfile-jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'files[]=@example-file;type=application/octet-stream'import requests
url = "https://api.githits.dev/v1/experimental/lockfile-jobs"
files = { "files[]": ("example-file", open("example-file", "rb"), "application/octet-stream") }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('files[]', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.githits.dev/v1/experimental/lockfile-jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.githits.dev/v1/experimental/lockfile-jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.githits.dev/v1/experimental/lockfile-jobs"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.githits.dev/v1/experimental/lockfile-jobs")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.githits.dev/v1/experimental/lockfile-jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"events_url": "/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events",
"expires_at": "2026-10-10T12:00:00Z",
"id": "01900000-0000-7000-8000-000000000001",
"result_url": "/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result",
"state": "queued",
"status_url": "/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001"
}Authorizations
Headers
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.
1 - 64^[A-Za-z0-9_-]{1,64}$Query Parameters
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.
sbom, audit 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.
cyclonedx, spdx, text, json 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.
2, 3 Body
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.
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.
1 - 256 elementsOptional 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.
cyclonedx, spdx, text, json Response
The upload was admitted and queued for asynchronous analysis.
Canonical relative URL for the job's server-sent event stream.
^/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$"/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events"
Canonical relative URL for retrieving the completed analysis document.
^/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$"/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result"
curl --request POST \
--url https://api.githits.dev/v1/experimental/lockfile-jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'files[]=@example-file;type=application/octet-stream'import requests
url = "https://api.githits.dev/v1/experimental/lockfile-jobs"
files = { "files[]": ("example-file", open("example-file", "rb"), "application/octet-stream") }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('files[]', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.githits.dev/v1/experimental/lockfile-jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.githits.dev/v1/experimental/lockfile-jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.githits.dev/v1/experimental/lockfile-jobs"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.githits.dev/v1/experimental/lockfile-jobs")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.githits.dev/v1/experimental/lockfile-jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files[]\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"events_url": "/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events",
"expires_at": "2026-10-10T12:00:00Z",
"id": "01900000-0000-7000-8000-000000000001",
"result_url": "/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result",
"state": "queued",
"status_url": "/v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001"
}