Skip to content
Craftifact

SBOM upload API

Reference for the CycloneDX SBOM upload endpoint, including inputs, target selection, and response shapes.

POST /api/sbom/upload/

Purpose

  • accept one CycloneDX JSON document
  • bind it to exactly one existing target
  • queue it for parsing

Request

Query parameters

Use exactly one target mode.

Package artifact mode

  • artifact_id : required

Use this when the SBOM belongs to an existing package artifact such as a Python wheel or npm tarball. Copy the artifact_id from the Artifact ID row in the artifact details panel in Craftifact, or resolve it first through the Artifact lookup API. The upload endpoint does not create a new package artifact for you first.

OCI mode

  • oci_digest: required
  • repository: required

Use this when the SBOM belongs to existing OCI content identified by digest.

Name Required Type
artifact_id Optional string · uuid
oci_digest Optional string · pattern: ^sha256:[a-f0-9]{64}$
repository Optional string

Header aliases

Use these when your automation prefers headers over query parameters.

Name Required Type
X-Sbom-Artifact-Id Optional string · uuid
X-Sbom-Oci-Digest Optional string · pattern: ^sha256:[a-f0-9]{64}$
X-Sbom-Repository Optional string

Request body

The body must be one JSON object in CycloneDX format.

Minimum practical shape:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6"
}

Validation rules:

  • body must be valid JSON
  • top-level value must be an object
  • bomFormat must be CycloneDX
  • specVersion must be a string

JSON payload

Required
bomFormat Required

string · const: CycloneDX

Must be CycloneDX.
specVersion Required

string

CycloneDX specification version string.

Additional object properties are allowed.

Example JSON 
{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6"
}

Responses

Common status codes:

  • 201 Created: the SBOM was accepted and queued for parsing.
  • 400 Bad Request: target selection is invalid or the body is not valid CycloneDX JSON.
  • 401 Unauthorized: no valid programmatic credentials were provided.
  • 403 Forbidden: the caller lacks the required scope or repository permission.
  • 404 Not Found: the referenced artifact or OCI content does not exist.
  • 413 Payload Too Large: the configured size limit or repository quota would be exceeded.
201

Created

The SBOM was accepted and queued for parsing.
document_id Required

string · uuid

UUID of the queued SBOM document.
status Required

string · enum: pending

Initial processing state after the upload was accepted.
201 Example JSON 
{
  "document_id": "3f5d0a9d-4cbe-4e6a-b5b1-1b4c3930d9a1",
  "status": "pending"
}
400

Bad Request

Bad request. Typical causes include:

  • Neither artifact_id nor oci_digest was provided.
  • Both target modes were provided at once.
  • repository is missing in OCI mode.
  • The body is invalid JSON.
  • The body is not a JSON object.
  • The body is not valid CycloneDX JSON.
error Required

string

Human-readable error message for the rejected upload.
400 Example JSON 
{
  "error": "one of artifact_id or oci_digest is required"
}
401

Unauthorized

Authentication failed or no programmatic credentials were provided.
error Required

string

Human-readable error message for the rejected upload.
401 Example JSON 
{
  "error": "authentication required"
}
403

Forbidden

Forbidden. Typical causes include:

  • The token scope does not allow this repository family.
  • The caller lacks write or redeploy permission.
  • Redeploy is disabled for the target repository.
error Required

string

Human-readable error message for the rejected upload.
403 Example JSON 
{
  "error": "token scope does not permit this operation"
}
404

Not Found

Not found. Typical causes include:

  • artifact_id does not resolve to an uploaded artifact.
  • oci_digest together with repository does not resolve to uploaded OCI content.
error Required

string

Human-readable error message for the rejected upload.
404 Example JSON 
{
  "error": "artifact not found"
}
413

Payload Too Large

Payload too large. Typical causes include:

  • The SBOM exceeds the configured maximum size.
  • Repository quota would be exceeded by storing the uploaded SBOM blob.
error Required

string

Human-readable error message for the rejected upload.
413 Example JSON 
{
  "error": "document exceeds maximum size (10485760 bytes)"
}

Examples

curl: upload and bind to artifact 
curl \
  -X POST \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @dist/example-cyclonedx.json \
  "https://packages.example.com/api/sbom/upload/?artifact_id=ARTIFACT_ID"
curl: OCI content 
curl \
  -X POST \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @image-cyclonedx.json \
  "https://packages.example.com/api/sbom/upload/?oci_digest=sha256:DIGEST&repository=libs-release"