Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Gets a list of spotlight result objects for the specified account (retrieved from JWT) and the buyer group (retrieved from the API for the requesting user), filtered by an RQL query if applicable.
The Spotlight object represents a collection of spotlighted objects and their definition, along with the RQL query used to retrieve items.
This object contains the following attributes:
id
string
The unique identifier for the spotlight object.
query
object
Represents the spotlightQuery object.
top
A list of the top five objects returned by the downstreamed RQL query.
total
integer
The total number of objects available for downstream RQL.
audit
object
Represents the audit object, which tracks changes to the spotlight object. For example, when the cache key was last refreshed and who initiated the action.
{
"id": "SPO-1234-5678-9012-3456-7890",
"query": {
"id": "SPQ-1234-2345",
"name": "Saved Orders",
"template": "savedOrdersClient"
},
"top": [
{
"id": "ORD-6637-5331-9984",
"audit": {
"updated": {
"at": "2024-05-28T09:00:22.945Z"
}
},
"icon": "/public/v1/catalog/products/PRD-6523-2229/icon",
"name": "Order ORD-8373-6076-7130"
}
],
"total": 1,
"audit": {
"updated": {
"at": "2024-05-28T09:00:22.945Z"
}
}
}The SpotlightTopItem object represents references to the platform objects picked up by SpotlightQuery.
SpotlightTopItem is used to provide data to the frontend template. It includes both core properties and object-specific properties. Spotlight operates as a service that is object-agnostic, meaning it does not maintain the schema of domain objects.
The SpotlightTopItem contract is a result of a downstreamed RQL query and is utilized as is in a JSON string. This indicates that the list of properties is object-specific and may change depending on the RQL query executed.
Use the Spotlight API to highlight key platform objects requiring attention.
The Spotlight API provides endpoints designed to highlight key platform objects that may need attention. These objects can include agreements, orders, subscriptions, invoices, and more.
The API consists of two primary endpoints: spotlightObject and spotlightQuery. With this API, you can:
List all spotlighted objects.
Invalidate or clear the cache for Spotlight objects.
id
string
The core unique identifier for each item.
href
string
A relative reference to object on API.
{object-specific-properties}
List of object specific properties, as a result of downstreamed RQL query.
{
"id": "ORD-6637-5331-9984",
"audit": {
"updated": {
"at": "2024-05-28T09:00:22.945Z"
}
},
"icon": "/public/v1/catalog/products/PRD-6523-2229/icon",
"name": "Order ORD-8373-6076-7130"
} List the defined spotlight queries.
Get details for a specific spotlight query.
Update an existing spotlight query.
Review the shared API docs before you work with the spotlight resources.
The Spotlight API is built around the following core resources:
SpotlightObject – Represents a collection of spotlighted objects.
SpotlightTopItem – Represents individual top result items identified by spotlightQuery.
SpotlightQuery – Represents the search query used to retrieve spotlighted data.
The API is organized into a single collection containing a set of operations. Access to these operations varies by role, depending on whether you are a client, vendor, or operations user.
Refer to the following capability matrix to see which roles are authorized to perform specific operations within this collection:
GET
Returns a list of spotlight result objects filtered by RQL query.
vendor, client, ops
POST
Invalidates all cache keys for the account and buyer group.
vendor, client, ops
POST
Invalidates cache for a specific spotlight object.
vendor, client, ops
POST
Returns a list of spotlight queries.
vendor, client, ops
GET
Gets a spotlight query.
vendor, client, ops
PUT
Updates the definition or configuration of a spotlight query.
vendor, client, ops
A Spotlight Query defines the RQL query used to retrieve spotlighted objects from a collection.
This object contains the following attributes:
id
string
Invalidates the cache for a specific spotlight object.
Invalidates all cache objects for the user.
The unique ID for the query itself.
name
string
The name of the query (core property).
template
string
The name of the UI template used to render data (core property).
invalidation
invalidationStructure
Settings for invalidating cached data.
interval
string
Interval for invalidating cached data.
{
"id": "SPQ-1234-2345",
"name": "Saved Orders",
"template": "savedOrdersClient",
"invalidation": {
"interval": "1:00:00"
}
}OK
GET /public/v1/spotlight/objects HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
OK
{
"$meta": {
"pagination": {
"offset": 1,
"limit": 1,
"total": 1
},
"omitted": [
"text"
]
},
"data": [
{
"id": "text",
"audit": {
"created": {},
"updated": {}
},
"$meta": {
"omitted": [
"text"
]
},
"total": 1,
"top": [],
"query": {
"id": "text",
"audit": {},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"template": "text",
"invalidation": {
"interval": "text"
},
"filter": "text",
"scope": "text"
},
"name": "text"
}
]
}id of entity
Created
Bad Request
Not Found
PUT /public/v1/spotlight/queries/{id} HTTP/1.1
Host: api.platform.softwareone.com
Content-Type: application/json
Accept: */*
Content-Length: 105
{
"name": "text",
"template": "text",
"rqlFilter": "text",
"scope": "text",
"moduleId": "text",
"moduleCode": "text"
}{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"template": "text",
"invalidationInterval": "text",
"invalidateOnDateChange": true,
"filter": "text",
"scope": "text"
}No Content
No content
POST /public/v1/spotlight/objects/{id}/refresh HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
No Content
No content
No Content
No content
POST /public/v1/spotlight/objects/-/refresh HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
No Content
No content
OK
Not Found
GET /public/v1/spotlight/queries/{id} HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"template": "text",
"invalidationInterval": "text",
"invalidateOnDateChange": true,
"filter": "text",
"scope": "text"
}OK
GET /public/v1/spotlight/queries HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
OK
{
"$meta": {
"pagination": {
"offset": 1,
"limit": 1,
"total": 1
},
"omitted": [
"text"
]
},
"data": [
{
"id": "text",
"audit": {
"created": {},
"updated": {}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"template": "text",
"invalidationInterval": "text",
"invalidateOnDateChange": true,
"filter": "text",
"scope": "text"
}
]
}