Upload API | boring.tools docs

The upload endpoint is the stable, supported interface for automation. Everything else is available in the app.

Endpoint

POST https://api.boring.tools/v1/sbom/upload
Content-Type: multipart/form-data

Authentication

Send an upload key (see CI integration) in one of these headers:

x-api-key: bt_sbom_...
Authorization: Bearer bt_sbom_...

A project key can only upload into its own project; an organization key into any project of the organization.

Form fields

Field	Required	Description
`file`	yes	CycloneDX or SPDX JSON, up to 25 MB
`projectId`	yes	ID of the project to upload into
`versionName`	no	Version name; defaults to the SBOM root component’s version
`artifactName`	no	Artifact name; defaults to the SBOM root component’s name
`repository`	no	Repository URL, stored for traceability
`commit`	no	Commit SHA
`branch`	no	Branch name
`pipelineUrl`	no	Link to the CI run

Versions and artifacts that don’t exist yet are created automatically.

Example

curl --fail -X POST https://api.boring.tools/v1/sbom/upload \
  -H "x-api-key: $BORING_TOOLS_KEY" \
  -F projectId=6f1c2e7a-0b8d-4c55-9a43-2f7e1d9b3c10 \
  -F versionName=v2.4.0 \
  -F commit=$(git rev-parse HEAD) \
  -F file=@sbom.json

Responses

202 Accepted — the file is stored and queued for import:

{
  "id": "0d6a8f6e-3b1f-4f0e-9a6e-5b2c7d8e9f01",
  "status": "pending",
  "componentCount": 0,
  "vulnerabilityCount": 0
}

Import and analysis run asynchronously. A file that turns out to be invalid is still accepted here and is shown as failed, with the reason, in the project.

Status	Meaning
`400`	No file, or a malformed request
`401`	Missing, invalid or deleted upload key
`403`	Project key used for a different project
`404`	Project not found in the key’s organization
`413`	File larger than 25 MB