Powered by Redocly

Revenera SBOM Insights API

Download OpenAPI specification:Download

Revenera SBOM Insights offers APIs to manage your Software Bill of Materials (SBOM) via buckets and parts. It supports manual software parts creation as well as ingestion of SBOMs in various formats. It also supports various queries into the constructed SBOM data.

Archetypes

View All Archetypes

Retrieve all the archetypes.

Archetypes can be filtered using any 'one' of the following parameters.

parameter description
ids comma separated list of archetype ids
categories comma separated list of categories. For e.g : part_types, bucket_types, origin_types, link_types, file_types etc
trailId provide job id to list all the records that was created/updated during the job run

Required security scopes for GlobalSession:

  • sbom:archetype:index
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

query Parameters
ids
string

comma separated list of archetype ids

categories
string

comma separated list of categories

trailId
integer <int64>

job that created/modified the record

offset
integer >= 1
Default: 1

The page number in the results at which to start fetching results. The default is the first page.

limit
integer <= 100
Default: 100

The maximum number of results per page. The default (and overall maximum) value is 100.

sort
string
Default: ""

Sort the query results on the field specified for the 'field' property. The sort direction is defined by the 'order' property.

order
string^(?i)(asc|desc)$
Default: "asc"

Order the sorted results as ascending or descending. Use ASC or DESC for the value.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/archetypes
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Archetype

Create an archetype. Required security scopes for GlobalSession:

  • sbom:archetype:create
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
category
required
string

Following are the 'categories' that the system supports. Specifying a category outside this list does not cause an error, instead creates an archetype with the given 'category'. * bucket_types * part_types * file_sub_types * file_types * link_types * origin_types

key
required
string

archetype key

label
required
string

archetype label

source
string

Following are the 'source' that the system supports that can be used to map the archetype. Specifying a source outside this list does not cause an error. * internal * cyclonedx * spdx

Responses
201

Created response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

post/sbom/v1/orgs/{orgId}/archetypes
Request samples
{
  • "category": "part_types",
  • "key": "app_key",
  • "label": "Application Name",
  • "source": "internal"
}
Response samples
application/json
{
  • "id": 101
}

View Information for an Archetype

Retrieve an archetype Required security scopes for GlobalSession:

  • sbom:archetype:show
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

archetypeId
required
integer

archetype id

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/archetypes/{archetypeId}
Response samples
application/json
{
  • "category": "bucket_types",
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "id": 101,
  • "key": "application_type",
  • "label": "Application Name",
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "orgId": 38808,
  • "source": "custom",
  • "trailId": 22
}

Update Archetype

Update an existing archetype Required security scopes for GlobalSession:

  • sbom:archetype:update
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

archetypeId
required
integer

archetype id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
category
string

Following are the 'categories' that the system supports. Specifying a category outside this list does not cause an error, instead creates an archetype with the given 'category'. * bucket_types * part_types * file_sub_types * file_types * link_types * origin_types

key
string

archetype key

label
string

archetype label

source
string

Following are the 'source' that the system supports that can be used to map the archetype. Specifying a source outside this list does not cause an error. * internal * cyclonedx * spdx

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

put/sbom/v1/orgs/{orgId}/archetypes/{archetypeId}
Request samples
{
  • "category": "bucket_types",
  • "key": "app_key",
  • "label": "Application Name",
  • "source": "internal"
}
Response samples
application/json
{
  • "category": "bucket_types",
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "id": 101,
  • "key": "application_type",
  • "label": "Application Name",
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "orgId": 38808,
  • "source": "custom",
  • "trailId": 22
}

Delete Archetype

Delete an existing archetype Required security scopes for GlobalSession:

  • sbom:archetype:delete
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

archetypeId
required
integer

archetype id

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

delete/sbom/v1/orgs/{orgId}/archetypes/{archetypeId}
Response samples
application/json
{
  • "id": 101
}

Buckets

View All Buckets

Retrieves all the buckets for the given orgId.

Buckets can be filtered using any 'one' of the following parameters.

parameter description
ids comma separated list of bucket ids
name bucket name
trailId provide job id to list all the records that was created/updated during the job run

Required security scopes for GlobalSession:

  • sbom:bucket:index
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

query Parameters
ids
string

comma separated list of bucket ids

name
string

bucket name

trailId
integer <int64>

jobid that created/modified the record

offset
integer >= 1
Default: 1

The page number in the results at which to start fetching results. The default is the first page.

limit
integer <= 100
Default: 100

The maximum number of results per page. The default (and overall maximum) value is 100.

sort
string
Default: ""

Sort the query results on the field specified for the 'field' property. The sort direction is defined by the 'order' property.

order
string^(?i)(asc|desc)$
Default: "asc"

Order the sorted results as ascending or descending. Use ASC or DESC for the value.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/buckets
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Bucket

Create a bucket. Required security scopes for GlobalSession:

  • sbom:bucket:create
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
customFieldValues
string

org specific custom field values for that particular bucket

description
string

description of the bucket

name
required
string

bucket Name

originId
integer <int64>

origin of the bucket. A bucket id from which this bucket was cloned or copied from.

originTypeId
integer <int64>

origin type of the bucket. Ref: Archetypes api for details.

parentId
integer <int64>

parent bucket id

typeId
required
integer <int64>

type of the bucket. Ref: Archetypes api for details.

Responses
201

Created response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

post/sbom/v1/orgs/{orgId}/buckets
Request samples
{
  • "customFieldValues": "{'filedname1:value2, fieldname2:value2}",
  • "description": "short description of the bucket",
  • "name": "bucket name",
  • "originId": 202,
  • "originTypeId": 1,
  • "parentId": 1,
  • "typeId": 101
}
Response samples
application/json
{
  • "id": 205
}

View Information for a Bucket

Retrieve detailed information for the requested bucket Required security scopes for GlobalSession:

  • sbom:bucket:show
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

bucketId
required
integer <int64>

bucket id

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/buckets/{bucketId}
Response samples
application/json
{
  • "bucketType": {
    },
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "customFieldValues": {
    },
  • "description": "bucket describption",
  • "id": 205,
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "name": "my bucket",
  • "orgId": 38808,
  • "originId": 202,
  • "originType": "null",
  • "originTypeId": 0,
  • "parentId": 1,
  • "trailId": 22,
  • "typeId": 1
}

Update Bucket

Update bucket information for the given bucket id Required security scopes for GlobalSession:

  • sbom:bucket:update
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

bucketId
required
integer <int64>

bucket id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
customFieldValues
string

org specific custom field values for that particular bucket

description
string

description of the bucket

name
string

pucket Name

originId
integer <int64>

origin of the bucket. A bucket id from which this bucket was cloned or copied from.

originTypeId
integer <int64>

origin type of the bucket. Ref: Archetypes api for details.

parentId
integer <int64>

parent bucket id

typeId
integer <int64>

type of the bucket. Ref: Archetypes api for details.

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

put/sbom/v1/orgs/{orgId}/buckets/{bucketId}
Request samples
{
  • "customFieldValues": "{'filedname1:value2, fieldname2:value2}",
  • "description": "short description of the bucket",
  • "name": "bucket name",
  • "originId": 1,
  • "originTypeId": 1,
  • "parentId": 1,
  • "typeId": 101
}
Response samples
application/json
{
  • "bucketType": {
    },
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "customFieldValues": {
    },
  • "description": "bucket describption",
  • "id": 205,
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "name": "my bucket",
  • "orgId": 38808,
  • "originId": 202,
  • "originType": "null",
  • "originTypeId": 0,
  • "parentId": 1,
  • "trailId": 22,
  • "typeId": 1
}

Delete Bucket

Delete a bucket Required security scopes for GlobalSession:

  • sbom:bucket:delete
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

bucketId
required
integer <int64>

bucket id

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

delete/sbom/v1/orgs/{orgId}/buckets/{bucketId}
Response samples
application/json
{
  • "id": 205
}

Files

View All Files

Retrieve all the files

Files can be filtered using any 'one' of the following parameters.

parameter description
ids comma separated list of file ids
partId get all the files for a specific part id
trailId provide job id to list all the records that was created/updated during the job run

Required security scopes for GlobalSession:

  • sbom:file:index
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

query Parameters
ids
string

comma separated list of file ids

partId
integer <int64>

Identifies a part by ID.

trailId
integer <int64>

jobid that created/modified the record

offset
integer >= 1
Default: 1

The page number in the results at which to start fetching results. The default is the first page.

limit
integer <= 100
Default: 100

The maximum number of results per page. The default (and overall maximum) value is 100.

sort
string
Default: ""

Sort the query results on the field specified for the 'field' property. The sort direction is defined by the 'order' property.

order
string^(?i)(asc|desc)$
Default: "asc"

Order the sorted results as ascending or descending. Use ASC or DESC for the value.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/files
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create File

Creates a file Required security scopes for GlobalSession:

  • sbom:file:create
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
Array of objects (HashRequestBody)

multiple hash types and values of the file

linkId
integer <int64>

id of the other file it's linked to

linkTypeId
integer <int64>

type of link to the other file. Ref: Archetypes api for details.

name
required
string

name of the file

path
string

key

subTypeId
integer <int64>

sub type of the file. Ref: Archetypes api for details.

typeId
integer <int64>

type of file. Ref: Archetypes api for details.

Responses
201

Created response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

post/sbom/v1/orgs/{orgId}/files
Request samples
{
  • "hashes": [
    ],
  • "linkId": 323,
  • "linkTypeId": 345,
  • "name": "my_file.zip",
  • "path": "/source/download",
  • "subTypeId": 53,
  • "typeId": 2223
}
Response samples
application/json
{
  • "id": 305
}

View Information for a File

Retrieve detailed information for the requested file Required security scopes for GlobalSession:

  • sbom:file:show
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

fileId
required
integer <int64>

file id

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/files/{fileId}
Response samples
application/json
{
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "hashes": [
    ],
  • "id": 305,
  • "linkId": 86,
  • "linkTypeId": 75,
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "name": "my_file.zip",
  • "orgId": 38808,
  • "path": "/source/download",
  • "subTypeId": 53,
  • "trailId": 22,
  • "typeId": 305
}

Update File

Update file information Required security scopes for GlobalSession:

  • sbom:file:update
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

fileId
required
integer <int64>

file id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
Array of objects (HashRequestBody)

multiple hash types and values of the file

linkId
integer <int64>

id of the file that it's linked to

linkTypeId
integer <int64>

type of link to the file. Ref: Archetypes api for details.

name
string

name of the file

path
string

key

subTypeId
integer <int64>

sub type of the file. Ref: Archetypes api for details.

typeId
integer <int64>

type of file. Ref: Archetypes api for details.

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

put/sbom/v1/orgs/{orgId}/files/{fileId}
Request samples
{
  • "hashes": [
    ],
  • "linkId": 323,
  • "linkTypeId": 45,
  • "name": "my_file.zip",
  • "path": "/source/download",
  • "subTypeId": 53,
  • "typeId": 23
}
Response samples
application/json
{
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "hashes": [
    ],
  • "id": 305,
  • "linkId": 86,
  • "linkTypeId": 75,
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "name": "my_file.zip",
  • "orgId": 38808,
  • "path": "/source/download",
  • "subTypeId": 53,
  • "trailId": 22,
  • "typeId": 305
}

Delete File

Delete a file Required security scopes for GlobalSession:

  • sbom:file:delete
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

fileId
required
integer <int64>

file id

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

delete/sbom/v1/orgs/{orgId}/files/{fileId}
Response samples
application/json
{
  • "id": 305
}

Importer

Import SBOM Data

Import Software Bill Of Materials into the system Required security scopes for GlobalSession:

  • sbom:importer:import
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema: multipart/form-data
bucketId
required
integer <int64>

bucket id

file
required
string <byte>

file to be uploaded

fileName
string

name of the file

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

post/sbom/v1/orgs/{orgId}/import
Response samples
application/json
{
  • "jobId": 812,
  • "message": "Import job QUEUED. Check the /jobs/{jobId} api for details."
}

Jobs

View All Jobs

Retrieve all the Jobs for the given orgId.

Jobs can be filtered using any 'one' of the following parameters.

parameter description
status list all the jobs for the given status
bucketId list all the jobs for a bucketId

Required security scopes for GlobalSession:

  • sbom:job:index
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

query Parameters
status
string

list jobs by status

bucketId
integer <int64>

list jobs by bucket id

offset
integer >= 1
Default: 1

The page number in the results at which to start fetching results. The default is the first page.

limit
integer <= 100
Default: 100

The maximum number of results per page. The default (and overall maximum) value is 100.

sort
string
Default: ""

Sort the query results on the field specified for the 'field' property. The sort direction is defined by the 'order' property.

order
string^(?i)(asc|desc)$
Default: "asc"

Order the sorted results as ascending or descending. Use ASC or DESC for the value.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/jobs
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

View Information for a Job

Retrieve a Job Required security scopes for GlobalSession:

  • sbom:job:show
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

Organization id

jobId
required
integer <int64>

job id.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/jobs/{jobId}
Response samples
application/json
{
  • "bucketId": 205,
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "id": 812,
  • "input": {
    },
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "orgId": 38808,
  • "output": {
    },
  • "status": "queued / processing / completed",
  • "type": "import / others"
}

Parts

View All SBOM Parts

This API retrieves information about SBOM parts in the current Organization. These parts can be filtered using one of the following parameters.

Parameter Description
ids A comma-separated list of SBOM part IDs to retrieve only those parts.
bucketIds A comma-separated list of bucket IDs to retrieve only those SBOM parts in the specified buckets.
trailId The ID of a specific job to retrieve only those SBOM parts that were created or updated during the job's execution.

Required security scopes for GlobalSession:

  • sbom:part:index
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

The ID for the Organization in which you are managing SBOMs. This ID is included in your SBOM Insight URL

query Parameters
ids
string

A comma-separated list of SBOM part IDs to retrieve only those parts.

bucketIds
string

A comma-separated list of bucket IDs to retrieve only those SBOM parts in the specified buckets.

trailId
integer <int64>

The ID of a specific job to retrieve only those SBOM parts that were created or updated during the job's execution.

offset
integer >= 1
Default: 1

The page number in the results at which to start fetching results. The default is the first page.

limit
integer <= 100
Default: 100

The maximum number of results per page. The default (and overall maximum) value is 100.

sort
string
Default: ""

Sort the query results on the field specified for the 'field' property. The sort direction is defined by the 'order' property.

order
string^(?i)(asc|desc)$
Default: "asc"

Order the sorted results as ascending or descending. Use ASC or DESC for the value.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/parts
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create SBOM Part

Use this API to register an SBOM part. Required security scopes for GlobalSession:

  • sbom:part:create
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

The ID for the Organization in which you are managing SBOMs. This ID is included in your SBOM Insight URL.

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
additionalNotes
string

Additional notes about the SBOM part, such as detection notes produced by the scan or notes from a manual audit of the scanned files. This value can include multiple lines.

bucketId
required
integer <int64>

The ID of the bucket to which you are adding the new SBOM part.

catalogId
integer <int64>

The ID of the SBOM Catalog item associated with the SBOM part.

copyrightText
string

The copyright text associated with the SBOM part.

customFieldValues
string

Values for the organization-specific custom fields available to the bucket.

description
string

A description of the SBOM part.

fileIds
Array of integers <int64>

The ID of each file associated with the SBOM part.

linkId
integer <int64>

The ID of another SBOM part to which the current part is linked. The linked SBOM part must reside in the same bucket as the current part.

linkNotes
string

Notes about the link between the two SBOM parts.

linkTypeId
integer <int64>

The type of link between the two SBOM parts. Refer to the Archetypes section for more information.

name
required
string

The name of the SBOM part, usually referencing the name of the open-source, third-party, or commercial component that the part represents. The standard format of an SBOM part name is componentName version (license). However, this format can vary format.

noticesText
string

The content of licenses associated with the SBOM part. This value can include multiple lines.

originId
integer <int64>

The ID of the bucket from which the current bucket was cloned or copied.

originTypeId
integer <int64>

The type of origin for the bucket. Refer to the Archetypes section for more information.

purl
string

The package URL for the component represented by the SBOM part.

status
required
string

The status of the SBOM part.

typeId
required
integer <int64>

The SBOM part type, such as Application, Container, Library, or another. Refer to the Archetypes section for more information.

url
string

The URL of the forge repository for the component.

Responses
201

Created response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

post/sbom/v1/orgs/{orgId}/parts
Request samples
{
  • "additionalNotes": "Notes found from Automated Finding...",
  • "bucketId": 205,
  • "catalogId": 644,
  • "copyrightText": "Copyright (c) 2020 golden authors",
  • "customFieldValues": "{'field1': 'value1','field2': 'value2'}",
  • "description": "Module used to execute heavy tasks under forked processes in parallel... ",
  • "fileIds": [
    ],
  • "linkId": 323,
  • "linkNotes": "Note the following about the link established between MyComponent and OtherComponent...",
  • "linkTypeId": 345,
  • "name": "ComponentABC 1.0 (Apache 2.0)",
  • "noticesText": "The following lists the content of the licenses for the components used by this software ...",
  • "originId": 1,
  • "originTypeId": 1,
  • "purl": "pkg:alpine/alpine-keys@2.4-r0?arch=x86_64",
  • "status": "Approved",
  • "typeId": 1,
  • "url": "http://github.com/my/component"
}
Response samples
application/json
{
  • "id": 411
}

View Information for an SBOM Part

This API retrieves information about a specific SBOM part. Required security scopes for GlobalSession:

  • sbom:part:show
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

The ID for the Organization in which you are managing SBOMs. This ID is included in your SBOM Insight URL.

partId
required
integer <int64>

The ID for the SBOM part that you want to view.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

get/sbom/v1/orgs/{orgId}/parts/{partId}
Response samples
application/json
{
  • "additionalNotes": "Notes found from Automated Finding...",
  • "bucket": {
    },
  • "bucketId": 205,
  • "catalog": {
    },
  • "catalogId": 644,
  • "copyrightText": "Copyright (c) 2020 golden authors",
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "customFieldValues": {
    },
  • "description": "Module used to execute heavy tasks under forked processes in parallel... ",
  • "fileIds": [
    ],
  • "id": 411,
  • "internalNotes": {
    },
  • "linkId": 404,
  • "linkNotes": "Note the following about the link established between MyComponent and OtherComponent...",
  • "linkType": {
    },
  • "linkTypeId": 54,
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "name": "my bucket name",
  • "noticesText": "The following lists the content of the licenses for the components used by this software ...",
  • "orgId": 38808,
  • "originId": 545,
  • "originType": "Accusamus qui dolores rem ipsam.",
  • "originTypeId": 54,
  • "partType": {
    },
  • "purl": "pkg:alpine/alpine-keys@2.4-r0?arch=x86_64",
  • "status": "Reviewed / Not Reviewed / Pending",
  • "trailId": 22,
  • "typeId": 1,
  • "url": "http://github.com/my/component"
}

Update SBOM Part

This API updates information for an SBOM part. Required security scopes for GlobalSession:

  • sbom:part:update
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

The ID for the Organization in which you are managing SBOMs. This ID is included in your SBOM Insight URL.

partId
required
integer <int64>

The ID of the SBOM part that you want to update.

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
additionalNotes
string

Additional notes about the SBOM part, such as detection notes produced by the scan or notes from a manual audit of the scanned files. This value can include multiple lines.

bucketId
integer <int64>

The ID of the bucket to which you are adding the new SBOM part.

catalogId
integer <int64>

The ID of the SBOM Catalog item associated with the SBOM part.

copyrightText
string

The copyright text associated with the SBOM part.

customFieldValues
string

Values for the organization-specific custom fields available to the bucket.

description
string

A description of the SBOM part.

fileIds
Array of integers <int64>

The ID of each file associated with the SBOM part.

linkId
integer <int64>

The ID of another SBOM part to which the current part is linked. The linked SBOM part must reside in the same bucket as the current part.

linkNotes
string

Notes about the link between the two SBOM parts.

linkTypeId
integer <int64>

The type of link between the two SBOM parts. Refer to the Archetypes section for more information.

name
string

The name of the SBOM part, usually referencing the name of the open-source, third-party, or commercial component that the part represents. The standard format of an SBOM part name is componentName version (license). However, this format can vary format.

noticesText
string

The content of licenses associated with the SBOM part. This value can include multiple lines.

originId
integer <int64>

The ID of the bucket from which the current bucket was cloned or copied.

originTypeId
integer <int64>

The type of origin for the bucket. Refer to the Archetypes section for more information.

purl
string

The package URL for the component represented by the SBOM part.

status
string

The status of the SBOM part.

typeId
integer <int64>

The SBOM part type, such as Application, Container, Library, or another. Refer to the Archetypes section for more information.

url
string

The URL of the forge repository for the component.

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

put/sbom/v1/orgs/{orgId}/parts/{partId}
Request samples
{
  • "additionalNotes": "Notes found from Automated Finding...",
  • "bucketId": 205,
  • "catalogId": 1,
  • "copyrightText": "Copyright (c) 2020 golden authors",
  • "customFieldValues": "{'field1': 'value1','field2': 'value2'}",
  • "description": "Module used to execute heavy tasks under forked processes in parallel... ",
  • "fileIds": [
    ],
  • "linkId": 323,
  • "linkNotes": "Note the following about the link established between MyComponent and OtherComponent...",
  • "linkTypeId": 345,
  • "name": "ComponentABC 1.0 (Apache 2.0)",
  • "noticesText": "The following lists the content of the licenses for the components used by this software ...",
  • "originId": 1,
  • "originTypeId": 1,
  • "purl": "pkg:alpine/alpine-keys@2.4-r0?arch=x86_64",
  • "status": "Approved",
  • "typeId": 1,
  • "url": "http://github.com/ven/rep"
}
Response samples
application/json
{
  • "additionalNotes": "Notes found from Automated Finding...",
  • "bucket": {
    },
  • "bucketId": 205,
  • "catalog": {
    },
  • "catalogId": 644,
  • "copyrightText": "Copyright (c) 2020 golden authors",
  • "createdBy": {
    },
  • "createdOn": "2022-07-20 04:55:49",
  • "customFieldValues": {
    },
  • "description": "Module used to execute heavy tasks under forked processes in parallel... ",
  • "fileIds": [
    ],
  • "id": 411,
  • "internalNotes": {
    },
  • "linkId": 404,
  • "linkNotes": "Note the following about the link established between MyComponent and OtherComponent...",
  • "linkType": {
    },
  • "linkTypeId": 54,
  • "modifiedBy": {
    },
  • "modifiedOn": "2022-07-20 04:55:49",
  • "name": "my bucket name",
  • "noticesText": "The following lists the content of the licenses for the components used by this software ...",
  • "orgId": 38808,
  • "originId": 545,
  • "originType": "Libero iste consectetur corrupti minus.",
  • "originTypeId": 54,
  • "partType": {
    },
  • "purl": "pkg:alpine/alpine-keys@2.4-r0?arch=x86_64",
  • "status": "Reviewed / Not Reviewed / Pending",
  • "trailId": 22,
  • "typeId": 1,
  • "url": "http://github.com/my/component"
}

Delete an SBOM Part

Un-register an SBOM part. Required security scopes for GlobalSession:

  • sbom:part:delete
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

The ID for the Organization in which you are managing SBOMs. This ID is included in your SBOM Insight URL.

partId
required
integer <int64>

The ID of the SBOM part that you want to unregister.

header Parameters
Authorization
string

JWT token used to perform authorization

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

404

Not Found response.

500

Internal Server Error response.

502

Bad Gateway response.

delete/sbom/v1/orgs/{orgId}/parts/{partId}
Response samples
application/json
{
  • "id": 411
}

Search SBOM Parts

Search for SBOM Parts using various filters and other parameters that you construct based on a search model within the request body.

About the Search Model

To perform a search of SBOM parts in the Organization to which you are currently connected, you must use the search model (described in the next sections) to construct an appropriate search within the request body of this API. The main attribute of the model is a query that defines parameters for the data you want to retrieve. The query can include both filters that refine search results and a sort definition that orders these results in the response. The search construction must be in JSON format and contain the search attributes described in the next section.

Search Attributes

The search model consists of the following attributes.

Name Required Description
query Yes The primary search attribute consisting of one or more properties that define the search. See the "Query Properties" section below.
offset No The page number in the results at which to start fetching results. The default is the first page.
limit No The maximum number of results per page. The default (and overall maximum) value is 100.

Query Properties

The following properties are defined within the "query" search attribute.

Name Required Description
where No The clause containing one or more criteria (in the form of field definitions) that a given SBOM part must match in order to be included in the search results. The search uses AND logic to process these criteria, meaning that a given part must match all the criteria in the "where" clause to be considered a match. The "where" is required only if the query has no "or" clause.
or No The clause that further refines the search results of the "where" clause. The "or" clause defines two or more criteria to which OR logic is applied, meaning that an SBOM part resulting from the "where" search must match at least one of the criteria in the "or" clause to be included in the final search results. The "or" clause is required only if the query has no "where" clause.
sort No The definition specifying one or more fields on which to sort the search results. By default, the results are sorted on the SBOM part id field in ascending order. Include the "sort" definition to override this default behavior. Refer to the "Results Sorting" section below for more information.

Field Definitions

The "where" and "or" clauses within the "query" search attribute contain one or more field definitions (that is, search criteria) by which to filter the SBOM parts. Each criterion contains the following properties.

Name Required Description
field Yes The field against which the part should be searched. Refer the "Searchable Fields" section for the list of fields that you can use to search SBOM parts.
operator No The action portion of the search criterion. By default, the "equals" operator is used. To override this value, specify another valid operator as listed in the "Operators" section below.
value Yes The value that is matched against the value for the same field in an SBOM part definition. If providing a value for the name or bucket.name field, you can enter the full name (for an exact name match) or a string within the name. Always supply the value (whether a string, integer, float, date, or boolean) as a string enclosed in double quotes.

Note: All searches are case-insensitive so you can use any case or case combination for the values of the name, operator, and value properties in a field definition. The results will be the same.

Searchable & Sortable Fields

The following table lists the fields (used in the SBOM part definition) by which SBOM parts can be filtered during a search. A field definition (that is, a search criterion) in the "where" or "or" clause must use a field name from this table for the "field" property. This table also includes each field's allowable operators in the field definition.

The names of the "searchable fields" match the names of their corresponding attributes returned in the response object. Consider that some of these fields identify attributes contained within a nested object in the response. The field name for this type of attribute uses qualifiers that reflect the attribute's hierarchy within the response.

For example, in the response, bucket is a nested object containing the attributes id, name, description, and other attributes describing the bucket. In the query, you can search by the bucket's name or ID within the bucket object by using the field name bucket.id or bucket.name (as listed in the table below), which matches the attribute name for the nested bucket in the response. Before including a field definition in the query, always check this table to ensure that you use the exact field name listed.

Additionally, when a valid field is used with an operator that it does not support, the system ignores the condition and returns all values for that field. Refer to this table to ensure that operator you specify for a field is supported by that field.

Field Description Supported Operators
name Name of the SBOM part equals, contains, starts_with, ends_with, in
bucketId ID of each bucket containing the SBOM parts you want to search equals, in
createdOn SBOM part creation date equals, between
modifiedOn Date that the SBOM part was last modified equals, between
bucket.id ID of the bucket containing the SBOM parts you want to search equals, in
bucket.name Name of the bucket containing the SBOM parts you want to search equals, contains, starts_with, ends_with, in
catalog.cvlProps.componentName Name of the component equals, contains, starts_with, ends_with, in
catalog.cvlProps.componentUrl URL of the component equals, contains, starts_with, ends_with, in
catalog.cvlProps.version.name Name of the component version, such as "2.9.3" equals, contains, starts_with, ends_with, in
catalog.cvlProps.version.purl Package URL (purl) of the version equals, contains, starts_with, ends_with, in
catalog.cvlProps.licenses.name Name of the license associated with the component version equals, contains, starts_with, ends_with, in
catalog.cvlProps.licenses.spdxIdentifier SPDX identifier of the license equals, contains, starts_with, ends_with, in
catalog.cvlProps.licenses.spdxName SPDX name of the license equals, contains, starts_with, ends_with, in
catalog.cvlProps.licenses.shortName Short name of the license equals, contains, starts_with, ends_with, in
catalog.cvlProps.licenses.url URL of the license equals, contains, starts_with, ends_with, in
vulnerability.name Security vulnerability ID (CVE or other) equals, contains, in
vulnerability.publishDate Publication date of the vulnerability equals, between
vulnerability.revisedDate Last revision date of the vulnerability equals, between
vulnerability.cvss2Score CVSS v2 score the of the vulnerability equals, between, greater_than, lesser_than
vulnerability.cvss3Score CVSS v3 score the of the vulnerability equals, between, greater_than, lesser_than

Supplying the Value for "value"

In a field definition, always supply the value for the value property (whether it is a string, integer, float, date, or boolean data type) as a string data type enclosed within double quotes. A value not enclosed in double quotes results in an error. For example, a value for the "bucket.id" field must be in double quotes even though it is an integer:

"field": "bucket.id"
"operator": "equals"
"value": "301"

Note: A date value must be in either YYYY-MM-DD, YYYY/MM/DD, or MM-DD-YYYY format (and placed in double quotes as mentioned above).

Operators

The following table lists the operators allowed in field definitions (that is, the filter criteria) set up in the "where" clause.

The term value in each operator description in the table refers to the value property in the field definition used in the query. For example, if a field definition uses the equals operator to process the value specified for the field bucket.name, the criterion syntactically reads "The value for bucket.name in the SBOM part definition must exactly match the value property for bucket.name in the field definition in the query."

Operator Description
equals Matches the value exactly
starts_with Starts with the given value
ends_with Ends with the given value
contains Contains the given value
in Matches at least one of the multiple values provided
between Matches within the given range
greater_than Is greater than the given value
lesser_than Is less than the given value
Using the IN Operator

When the "in" operator is used, multiple values entered for the "value" field in the field definition must be formatted as a comma-separated list (such as 209,265,266). The values in this field are processed using OR logic.

Using the BETWEEN Operator

When the "between" operator is used, two values must be entered for the "value" field in the field definition. The values are formatted as a comma-separated list (such as 2022-12-01,2023-01-31). If you enter the values in wrong order (with the later date first and the earlier date last, as in 2023-01-31,2022-12-01,), Code Insight will handle the order of the supplied values internally to ensure proper sorting.

AND/OR Logic

If multiple field definitions are defined in the "where" clause of the query, AND logic is used to process the definitions as criteria against SBOM parts during the search. When AND logic is applied, a given part must match all the defined criteria in order to be included in the search results.

If you want OR logic to be used when processing multiple criteria against SBOM parts, include the "or" clause in the query. When OR logic is applied, a part must match at least one of the criteria in order to be included in the search results.

Results Sorting

By default, search results are sorted in ascending order on the id field identifying each SBOM part. You can override this default by specifying one or more field names for the "field" property in the "sort" definition in the query. Specify the sorting order by entering ASC (for ascending) or DESC (for descending) for the "order" property in the definition.

Multiple fields are sorted in the sequence in which they are listed for the "field" property in the "sort" definition.

Note: You can sort on any field listed in the Searchable & Sortable Fields table.

The following shows the standard structure of a request and response used in an SBOM parts search.

Standard Request Format

The following illustrates the basic structure of a request used to search SBOM parts. The search model shows the format of search attributes, query properties, and field definitions.

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "bucket.name",
                "operator": "equals",
                "values": "test project"
            }
        ],
        "or": [
            {
                "field": "name",
                "operator": "contains",
                "values": "xyz"
            }
        ],
        "sort": [
            {
                "field": "createdOn",
                "order": "ASC"
            }
        ]
    },
    "offset": 1,
    "limit": 100
}

Standard Response Format

A standard response shows "data" and "meta" properties. The "data" attribute contains the actual results, while the "meta" attribute provides page configuration information for the results.

{
    "data": [
        {
            ...
        }
    ],
    "meta": {
        "total": 1,
        "offset": 1,
        "limit": 100
    }
}

Example Searches

The following examples illustrate some common searches that you can perform on SBOM parts.

Note: To conserve space, the response in many of these examples uses an ellipsis after the details for the first retrieved result. The ellipsis represents the remaining details for that result as well as all remaining results and their details.

Example 1: Filter to SBOM Parts in Specified Buckets

This search example retrieves only those SBOM parts found in specified buckets and then sorts these results by the part's creation date in ascending order.

Example 1 Request

The query in the following request body for Example 1 uses the "in" operator to retrieve all SBOM parts that belong to two buckets (identified by their Ids) and then sorts these results on the createdOn field in ascending order.

Note: If you want to retrieve all SBOM parts without a filter, provide empty brackets for the "where" clause, as in:

"where": [ ]

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "bucketId",
                "operator": "in",
                "value": "101,201"
            }
        ]
        ,"sort" :[ 
            {
                "field": "createdOn",
                "order": "asc"
            }
        ]
    }
}
Example 1 Response

The results show details for all SBOM parts found in each specified bucket, listing the parts in ascending order by their creation date.

{
    "data": [
        {
            "id": 123,
            "name": "testComponent",
            "bucketId": 101
            ...
        }
    ],
    "meta": {
        "total": 230,
        "offset": 1,
        "limit": 100
    }
}

Example 2: Retrieve SBOM Parts Whose Name Contain "apache"

This search example retrieves all SBOM parts whose name contains the string "apache".

Example 2 Request

The "where" clause in the query uses the "contains" operator to search for SBOM parts that have the string "apache" in their name. The search is performed across all buckets in the organization.

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "name",
                "operator": "contains",
                "value": "Apache"
            }
        ]
    }
}
Example 2 Response

The response shows details for every SBOM part that contains "apache" in its name. 

{
    "data": [
        {
            "id": 123,
            "name": "Apache Commons",
            "bucketId": 110
            ...
        }
    ],
    "meta": {
        "total": 2,
        "offset": 1,
        "limit": 100
    }
}

Example 3: Search Multiple Buckets to Retrieve SBOM Parts That Meet Multiple Criteria

This search example searches two buckets for all SBOM parts that were last modified within a specified date range.

Example 3 Request

The following shows a request body for Example 3. The search uses the AND logic of the "where" clause to locate all SBOM parts that belong to either "Test Bucket" or "Mixed Bucket" and, of those parts, only those that were last updated between November 1 and November 30, 2022.

Note: This request lists the "modifiedOn" field values for the "between" operator in wrong order (with the later date first and the earlier date last). When a wrong order is used in the request, Code Insight will internally re-order out-of-order dates for the "between" operator to ensure that proper sorting occurs. 

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "bucket.name",
                "operator": "in",
                "value": "Test Bucket,Mixed Bucket"
            }
            ,{
                "field": "modifiedOn",
                "operator": "between",
                "value": "2022-11-30,2022-11-01"
            }
        ]
    }
}
Example 3 Response

The response shows details for the SBOM parts belonging either bucket that were modified within the given date range.

{
    "data": [
        {
            "id": 123,
            "name": "Apache Commons",
            "bucketId": 115,
            "modifiedOn": "2022-11-15 13:03:50",
            ...
        }
    ],
    "meta": {
        "total": 5,
        "offset": 1,
        "limit": 100
    }
}

Example 4: Search One Bucket to Retrieve SBOM Parts That Meet at Least One of Multiple Criteria

This search example searches a single bucket for those SBOM parts whose name contains one or more specified strings.

Example 4 Request

The query in the following request body for Example 4 uses an "or" clause to search for those SBOM parts whose name contains either "abc" or "xyz" or both strings. The search is performed on the SBOM parts in the bucket specified in "where" clause. The results are listed in descending order on the part name.

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "bucket.name",
                "operator": "equals",
                "value": "test project"
            }
        ],
        "or": [
            {
                "field": "name",
                "operator": "contains",
                "value": "abc"
            },
            {
                "field": "name",
                "operator": "contains",
                "value": "xyz"
            }
        ],
        "sort": [
            {
                "field": "name",
                "order": "desc"
            }
        ]
    }
}
Example 4 Response

The response shows details for each SBOM part whose name contains one or both specified strings within the bucket "test bucket" (whose ID is 110).

{
    "data": [
        {
            "id": 123,
            "name": "Apache Commons abc",
            "bucketId": 110,
            ...
        }
    ],
    "meta": {
        "total": 5,
        "offset": 1,
        "limit": 100
    }
}

Example 5: Search Multiple Buckets to Retrieve SBOM Parts That Meet at Least One of Multiple Criteria

This example searches two buckets for all SBOM parts that have one or more security vulnerabilities whose scores are within a certain range.

Example 5 Request

The following shows the request body for Example 5. The query uses an "or" clause to search for those SBOM parts that have at least one security vulnerability with either a CVSSv3 score between the range of 9.0 and 10.0 or a CVSSv2 score greater than 9.0. The search is performed on the SBOM parts belonging to the two buckets identified in the "where" clause. 

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "bucketId",
                "operator": "in",
                "value": "1,2"
            }
        ],
        "or": [
            {
                "field": "vulnerability.cvss3Score",
                "operator": "between",
                "value": "9.0, 10.0"
            },
            {
                "field": "vulnerability.cvss2Score",
                "operator": "greater_than",
                "value": "9.0"
            }
        ]
    },
    "offset": 1
}
Example 5 Response

The response shows details for each SBOM part (in the two buckets specified) that have one or more security vulnerabilities whose scores are within either of the indicated ranges.

{
    "data": [
        {
            "id": 123,
            "name": "Apache Commons",
            "bucketId": 110,
            ...
        }
    ],
    "meta": {
        "total": 5,
        "offset": 1,
        "limit": 100
    }
}

Example 6: Search All SBOM Parts to Retrieve Those That Meet Multiple Criteria

This search example retrieves those SBOM parts that meet multiple license criteria. The search is performed across all buckets in the organization.

Example 6 Request

The query in the following request body for Example 6 searches for those SBOM parts that meet both of these criteria across all buckets:

  • A license SPDX identifier starting with "mit"
  • A license short name containing string "mit"

Notice the following about the example request body:

  • Each criterion shows a field name for a nested-object attribute (such as catalog.cvlProps.licenses.spdxIdentifier), as used in the response object. For more information about nested-object attributes, see "Searchable & Sortable Fields".
  • The query uses a "where" clause to identify one criterion and an "or" clause to identify the second criterion. However, the single criterion in the "or" clause renders the "or" operation meaningless so that both criteria end up being processed with AND logic. Unlike the example, the best practice in this case would be to set up a "where" clause that includes both criteria (and omit the "or" clause).

Note: If you want to broaden the search, you can omit the "where" clause altogether and add both criteria to an "or" clause that searches for all SBOM parts that meet at least one of the criteria.

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "catalog.cvlProps.licenses.spdxIdentifier",
                "operator": "starts_with",
                "value": "mit"
            }
        ],
        "or": [
            {
                "field": "catalog.cvlProps.licenses.shortName",
                "operator": "contains",
                "value": "mit"
            }
        ]
    },
    "offset": 1
}
Example 6 Response

The response shows details for each SBOM part that meets at least one of the license criteria. 

{
    "data": [
        {
            "id": 123,
            "name": "Apache Commons",
            "bucketId": 110,
            "catalog": {
                "cvlProps": {
                    "licenses": [
                        {
                            "id": 7,
                            "name": "MIT License",
                            "shortName": null,
                            "url": "https://spdx.org/licenses/MIT.html",
                            "spdxIdentifier": "MIT",
                            "spdxName": "MIT license"
                        }
                    ]
                }
                ...
            }
        }
    ],
    "meta": {
        "total": 5,
        "offset": 1,
        "limit": 100
    }
}

Example 7: Attempt to Retrieve SBOM Parts With Invalid "field" Name

This example demonstrates a search that fails because an invalid field name is specified for the "field" property in a field definition.

Example 7 Request

The query in following request body for Example 7 is set up to search for SBOM parts whose field "invalid.field.name" contains either "Test Bucket" or Mixed Bucket" as a value. 

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "invalid.field.name",
                "operator": "in",
                "value": "Test Bucket,Mixed Bucket"
            }
        ]
    }
}
Example 7 Response

The response returns a "400 Bad Request" error because no field with the name "invalid.field.name" is used in an SBOM part definition.

{
    "name": "bad_request",
    "id": "Z6Pg9Bps",
    "message": "invalid field(s) / operator(s) : invalid.field.name ",
    "temporary": false,
    "timeout": false,
    "fault": false
}

Example 8: Retrieve SBOM Parts With Invalid "operator"

This example demonstrates a search failure due to an invalid "operator" used in the query.

Example 8 Request

The query in the following request body for Example 8 uses an unknown operator (called "invalid-operator") in the field definition. 

POST /parts/search
{
    "query": {
        "where": [
            {
                "field": "name",
                "operator": "invalid-operator",
                "value": "Test Bucket,Mixed Bucket"
            }
        ]
    }
}
Example 8 Response

The response returns a "400 Bad Request" error.

{
    "name": "bad_request",
    "id": "Z6Pg9Bps",
    "message": "invalid field(s) / operator(s) : invalid-operator ",
    "temporary": false,
    "timeout": false,
    "fault": false
}

   

Required security scopes for GlobalSession:

  • sbom:part:search
SecurityGlobalSession_header_Authorization
Request
path Parameters
orgId
required
integer

The ID for the Organization in which you are managing SBOMs within the SBOM Insights connection.

header Parameters
Authorization
string

JWT token used to perform authorization

Request Body schema:
limit
integer <= 100
Default: 100

The maximum number of results per page. The default (and overall maximum) value is 100.

offset
integer >= 1
Default: 1

The page number in the results at which to start fetching results. The default is the first page.

required
object non-empty

The primary attribute of a search consisting of at least a 'where' or an 'or' clause and an optional 'sort' definition.

Responses
200

OK response.

400

Bad Request response.

401

Unauthorized response.

403

Forbidden response.

500

Internal Server Error response.

502

Bad Gateway response.

post/sbom/v1/orgs/{orgId}/parts/search
Request samples
{
  • "limit": 10,
  • "offset": 1,
  • "query": {
    }
}
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}