Asset service#
An asset is a physical entity within an organization, such as a vehicle or ground station. Assets are comprised of some metadata about the data, as well as a set of data scopes that define the data belonging to the asset. API endpoints allow for CRUD operations on asset objects.
OpenAPI file: nominal.asset.v2.json
Endpoints#
Create asset#
POST /asset/v2/assets
Creates a new asset.
Body
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of string
linksarray ofLink
Fields of
Linktitlestring
urlstring
dataScopesarray ofCreateAssetDataScopeThe data scopes associated with the asset.
Fields of
CreateAssetDataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields required
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
attachmentsarray of string
workspacestringThe workspace in which to create the asset. If not provided, the asset will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured. All data scopes, attachments, and asset types must be in the same workspace.
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValuerequired
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. Mutually exclusive with data and nonempty data_scopes. Must be readable and in the asset’s workspace. Composition datasets attach directly and cannot already back an asset. Raw datasets are wrapped in a new pipeline without changing the source, so the response’s data may differ from this RID. At least 1 character.
typesarray of stringTypes to attach. Empty attaches none. At most 10 types. At most 10 items.
dataAssetDataThe pipeline or raw dataset the asset reads. Mutually exclusive with dataset_rid and nonempty data_scopes; omit all three for scope-based creation. The caller must be able to view it, and it must be unarchived, in the asset’s workspace, and not already read by another asset.
Fields of
AssetData- one of
pipelineRid,datasetRidrequired
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
Response
assetAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"seriesTags": {
"<key>": "<value>"
}
}
],
"attachments": [
"<attachments>"
],
"workspace": "<workspace>",
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"types": [
"<types>"
],
"data": {
"pipelineRid": "<pipeline rid>"
}
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets",
headers={"Authorization": "Bearer <api key>"},
json={
"title": "<title>",
"description": "<description>",
"properties": {"<key>": "<value>"},
"labels": ["<labels>"],
"links": [{"title": "<title>", "url": "<url>"}],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
"attachments": ["<attachments>"],
"workspace": "<workspace>",
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
"datasetRid": "<dataset rid>",
"types": ["<types>"],
"data": {"pipelineRid": "<pipeline rid>"},
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets",
headers={"Authorization": "Bearer <api key>"},
json={
"title": "<title>",
"description": "<description>",
"properties": {"<key>": "<value>"},
"labels": ["<labels>"],
"links": [{"title": "<title>", "url": "<url>"}],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
"attachments": ["<attachments>"],
"workspace": "<workspace>",
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
"datasetRid": "<dataset rid>",
"types": ["<types>"],
"data": {"pipelineRid": "<pipeline rid>"},
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets",
headers={"Authorization": "Bearer <api key>"},
json={
"title": "<title>",
"description": "<description>",
"properties": {"<key>": "<value>"},
"labels": ["<labels>"],
"links": [{"title": "<title>", "url": "<url>"}],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
"attachments": ["<attachments>"],
"workspace": "<workspace>",
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
"datasetRid": "<dataset rid>",
"types": ["<types>"],
"data": {"pipelineRid": "<pipeline rid>"},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"asset": {
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
}
}
Get assets#
POST /asset/v2/assets/batch-get
Returns the assets for the given asset RIDs.
Body
ridsarray of string
Response
responsesmap of string toAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/batch-get" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"rids": [
"<rids>"
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"responses": {
"<key>": {
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
}
}
}
Get assets by data source#
POST /asset/v2/assets/by-data-source/{dataSourceRid}
Returns all assets with the given data source as a data scope.
Path parameters
dataSourceRidstring required
Response
assetsarray ofAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/by-data-source/<data source rid>" \
-H "Authorization: Bearer <api key>"
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/by-data-source/<data source rid>",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/by-data-source/<data source rid>",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/by-data-source/<data source rid>",
headers={"Authorization": "Bearer <api key>"},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"assets": [
{
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
}
]
}
Get asset data conformance#
POST /asset/v2/assets/data-conformance/batch-get
Reports, for each asset, whether its current data meets the data requirements of its types. Requirements are only enforced when a type is attached, so an asset whose data changed since may no longer meet them. Needs view permission on each asset; assets that are missing or not viewable are left out of the response.
Body
assetRidsarray of string1 to 100 unique asset RIDs. 1 to 100 items. No duplicates.
Response
assetsmap of string toAssetDataConformanceKeyed by asset RID. An asset none of whose types have data requirements has an empty types map. Assets that do not exist or that the caller cannot view are left out.
Fields of
AssetDataConformancetypesmap of string toTypeDataConformanceKeyed by type RID, with an entry for each type on the asset that has data requirements.
Fields of
TypeDataConformance- one of
met,unmet,unknown
metDataRequirementsMet
unmetDataRequirementsUnmet
Fields of
DataRequirementsUnmetmissingSeriesarray ofSeriesRequirementEvery required series that the asset’s data has no series of that name and type for, by name. Nonempty.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
unknownDataRequirementsUnknown
- one of
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/data-conformance/batch-get" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"assetRids": [
"<asset rids>"
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/data-conformance/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"assetRids": ["<asset rids>"]},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/data-conformance/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"assetRids": ["<asset rids>"]},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/data-conformance/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"assetRids": ["<asset rids>"]},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"assets": {
"<key>": {
"types": {
"<key>": {
"met": {}
}
}
}
}
}
Batch edit asset metadata#
POST /asset/v2/assets/metadata/batch-edit
Batch edits metadata across multiple assets. Supports rename/merge for labels and properties. If more than 1000 assets are targeted, this endpoint will throw a 400.
Body
assetSearchQuerySearchAssetsQueryAdditional search query to filter which assets are targeted by the edit. Source labels/properties from the metadata change are automatically included as filters.
Fields of
SearchAssetsQuery- one of 19 fields required
searchTextstring
exactSubstringstringA case-insensitive substring match of the title or description of the asset.
labelstring
labelsLabelsFilter
Fields of
LabelsFilteroperatorSetOperator
Values of
SetOperatorSET_OPERATOR_UNSPECIFIED
AND
OR
labelsarray of string
propertyProperty
Fields of
Propertynamestring
valuestring
propertyKeystringMatches assets that have a property with this key, regardless of value.
propertiesPropertiesFilter
Fields of
PropertiesFilternamestring
valuesarray of string
typeRidstring
assetTypesAssetTypesFilter
Fields of
AssetTypesFilterassetTypesarray of string
isStagedboolean
archivedboolean
andSearchAssetsQueryList
Fields of
SearchAssetsQueryListqueriesarray ofSearchAssetsQuery
notSearchAssetsQuery
workspacestring
numericPropertyNumericPropertyPredicate
Fields of
NumericPropertyPredicatenamestring
valuenumber
operatorPropertyComparisonOperator
Values of
PropertyComparisonOperatorPROPERTY_COMPARISON_OPERATOR_UNSPECIFIED
EQ
NEQ
GT
GTE
LT
LTE
numericPropertyRangeNumericPropertyRangePredicateMatches assets using an inclusive numeric property range.
Fields of
NumericPropertyRangePredicatenamestring
minnumber
maxnumber
operatorNumericPropertyRangeOperator
Values of
NumericPropertyRangeOperatorNUMERIC_PROPERTY_RANGE_OPERATOR_UNSPECIFIED
BETWEEN
NOT_BETWEEN
assetRidsAssetRidsFilterMatches assets whose RID is any of the provided RIDs.
Fields of
AssetRidsFilterassetRidsarray of string1 to 1,000 items.
livebooleanMatches assets with any dataset currently receiving live data.
operationMetadataChange
Fields of
MetadataChange- one of
renameLabel,renamePropertyKey,mergePropertyValuesForKeyrequired
renameLabelRenameLabel
Fields of
RenameLabelsourcearray of string
targetstring
renamePropertyKeyRenamePropertyKey
Fields of
RenamePropertyKeysourcearray of string
targetstring
onConflictConflictBehavior
Fields of
ConflictBehavior- one of
skip,overwriterequired
skipSkipOnConflict
overwriteOverwriteOnConflict
Fields of
OverwriteOnConflictpriorityarray of string
- one of
mergePropertyValuesForKeyMergePropertyValuesForKey
Fields of
MergePropertyValuesForKeykeystring
sourcearray of string
targetstring
- one of
Response
modifiedAssetRidsarray of stringRIDs for assets that were modified by the batch edit.
conflictingAssetRidsarray of stringRIDs for assets that matched the source filter but already had the target property key and were skipped (SkipOnConflict behavior). Empty for operations without conflict semantics or when using OverwriteOnConflict.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/metadata/batch-edit" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"assetSearchQuery": {
"searchText": "<search text>"
},
"operation": {
"renameLabel": {
"source": [
"<source>"
],
"target": "<target>"
}
}
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/metadata/batch-edit",
headers={"Authorization": "Bearer <api key>"},
json={
"assetSearchQuery": {"searchText": "<search text>"},
"operation": {"renameLabel": {"source": ["<source>"], "target": "<target>"}},
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/metadata/batch-edit",
headers={"Authorization": "Bearer <api key>"},
json={
"assetSearchQuery": {"searchText": "<search text>"},
"operation": {"renameLabel": {"source": ["<source>"], "target": "<target>"}},
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/metadata/batch-edit",
headers={"Authorization": "Bearer <api key>"},
json={
"assetSearchQuery": {"searchText": "<search text>"},
"operation": {
"renameLabel": {"source": ["<source>"], "target": "<target>"},
},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"modifiedAssetRids": [
"<modified asset rids>"
],
"conflictingAssetRids": [
"<conflicting asset rids>"
]
}
Search assets#
POST /asset/v2/assets/search
Searches for assets matching the given query.
Body
sortAssetSortOptions
Fields of
AssetSortOptionsisDescendingboolean
fieldAssetSortField
Values of
AssetSortFieldASSET_SORT_FIELD_UNSPECIFIED
NAME
CREATED_AT
MOST_RECENT_RUN_START
sortKeySortKeyField to sort by. Includes both field and property-based sorting. Must be supplied if field is not provided separately.
Fields of
SortKey- one of
field,property,numericPropertyrequired
fieldAssetSortField
propertySortProperty
Fields of
SortPropertynamestring
numericPropertySortPropertySorts numeric property values numerically. String-valued and missing properties are null and always sort last.
- one of
pageSizeintegerPage sizes greater than 10_000 will be rejected. Default pageSize is 100.
nextPageTokenstring
querySearchAssetsQuery
Fields of
SearchAssetsQuery- one of 19 fields required
searchTextstring
exactSubstringstringA case-insensitive substring match of the title or description of the asset.
labelstring
labelsLabelsFilter
Fields of
LabelsFilteroperatorSetOperator
Values of
SetOperatorSET_OPERATOR_UNSPECIFIED
AND
OR
labelsarray of string
propertyProperty
Fields of
Propertynamestring
valuestring
propertyKeystringMatches assets that have a property with this key, regardless of value.
propertiesPropertiesFilter
Fields of
PropertiesFilternamestring
valuesarray of string
typeRidstring
assetTypesAssetTypesFilter
Fields of
AssetTypesFilterassetTypesarray of string
isStagedboolean
archivedboolean
andSearchAssetsQueryList
Fields of
SearchAssetsQueryListqueriesarray ofSearchAssetsQuery
notSearchAssetsQuery
workspacestring
numericPropertyNumericPropertyPredicate
Fields of
NumericPropertyPredicatenamestring
valuenumber
operatorPropertyComparisonOperator
Values of
PropertyComparisonOperatorPROPERTY_COMPARISON_OPERATOR_UNSPECIFIED
EQ
NEQ
GT
GTE
LT
LTE
numericPropertyRangeNumericPropertyRangePredicateMatches assets using an inclusive numeric property range.
Fields of
NumericPropertyRangePredicatenamestring
minnumber
maxnumber
operatorNumericPropertyRangeOperator
Values of
NumericPropertyRangeOperatorNUMERIC_PROPERTY_RANGE_OPERATOR_UNSPECIFIED
BETWEEN
NOT_BETWEEN
assetRidsAssetRidsFilterMatches assets whose RID is any of the provided RIDs.
Fields of
AssetRidsFilterassetRidsarray of string1 to 1,000 items.
livebooleanMatches assets with any dataset currently receiving live data.
archivedStatusesArchivedStatusSetDefault search status is NOT_ARCHIVED when absent. A present empty set intentionally matches no assets.
Fields of
ArchivedStatusSetarchivedStatusesarray ofArchivedStatus
Values of
ArchivedStatusARCHIVED_STATUS_UNSPECIFIED
NOT_ARCHIVED
ARCHIVED
includeMatchCountbooleanWhen true, the response populates total_count with the number of assets matching the query. Defaults to false. Computing the count is an additional query whose cost grows with the size of the matching set, so only set this when the count is needed.
includeLivenessbooleanWhen true, each returned asset has is_live populated. Defaults to false, in which case is_live is left unset. Computing liveness is an additional query that can be slow in large workspaces, so only set this when is_live is needed. The
livequery filter does not require it.
Response
resultsarray ofAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
nextPageTokenstring
totalCountintegerThe number of assets matching the query, workspace, and archived filters. Present only when include_match_count was set to true on the request.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/search" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"sort": {
"isDescending": true,
"field": "NAME",
"sortKey": {
"field": "NAME"
}
},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {
"searchText": "<search text>"
},
"archivedStatuses": {
"archivedStatuses": [
"NOT_ARCHIVED"
]
},
"includeMatchCount": true,
"includeLiveness": true
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/search",
headers={"Authorization": "Bearer <api key>"},
json={
"sort": {"isDescending": True, "field": "NAME", "sortKey": {"field": "NAME"}},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {"searchText": "<search text>"},
"archivedStatuses": {"archivedStatuses": ["NOT_ARCHIVED"]},
"includeMatchCount": True,
"includeLiveness": True,
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/search",
headers={"Authorization": "Bearer <api key>"},
json={
"sort": {"isDescending": True, "field": "NAME", "sortKey": {"field": "NAME"}},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {"searchText": "<search text>"},
"archivedStatuses": {"archivedStatuses": ["NOT_ARCHIVED"]},
"includeMatchCount": True,
"includeLiveness": True,
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/search",
headers={"Authorization": "Bearer <api key>"},
json={
"sort": {
"isDescending": True,
"field": "NAME",
"sortKey": {"field": "NAME"},
},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {"searchText": "<search text>"},
"archivedStatuses": {"archivedStatuses": ["NOT_ARCHIVED"]},
"includeMatchCount": True,
"includeLiveness": True,
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"results": [
{
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
}
],
"nextPageToken": "<next page token>",
"totalCount": 1
}
Traverse links#
POST /asset/v2/assets/traverse-links
Follows a link from a batch of assets to the assets it reaches. Fails with LinkNotFound when the link does not exist or its source type is in a workspace the caller cannot view, and with AssetNotFound when a requested asset does not exist or the caller cannot view it. A custom method rather than an asset search, since each edge pairs a requested asset with what it reaches, and forward edges can end in a value that names no asset.
Body
assetRidsarray of stringThe assets to start from, archived or not. The caller must be able to view each one. The assets reached are always active, in both directions. 1 to 1,000 items.
linkLinkRefrequired
Fields of
LinkReflinkRidstring
directionLinkDirection
Values of
LinkDirectionLINK_DIRECTION_UNSPECIFIED
LINK_DIRECTION_FORWARDFrom assets of the link’s source type to the assets of its target type they link to.
LINK_DIRECTION_INVERSEFrom assets of the link’s target type to the assets of its source type that link to them.
pageSizeintegerDefaults to 100. From 1 to 1,000.
pageTokenstring
Response
edgesarray ofLinkEdgeOrdered by requested asset RID, then by linked asset RID. Inverse edges from assets the caller cannot view are left out. Every page but the last holds page_size edges; the last may hold fewer, or none.
Fields of
LinkEdgerequestedAssetRidstring
- one of
linkedAssetRid,unresolvedValue
linkedAssetRidstringAn active asset at the other end of the link that the caller can view.
unresolvedValuestringForward on a direct link only: the source property’s string value when it names no active asset of the target type that the caller can view, including blank values and values longer than any primary key. An asset the caller cannot view is indistinguishable from a missing one. Absent properties produce no edge.
nextPageTokenstringPresent while more edges may follow. It names only the last edge returned, so it reveals nothing about edges left out.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/traverse-links" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"link": {
"linkRid": "<link rid>",
"direction": "LINK_DIRECTION_FORWARD"
}
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/traverse-links",
headers={"Authorization": "Bearer <api key>"},
json={"link": {"linkRid": "<link rid>", "direction": "LINK_DIRECTION_FORWARD"}},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/traverse-links",
headers={"Authorization": "Bearer <api key>"},
json={"link": {"linkRid": "<link rid>", "direction": "LINK_DIRECTION_FORWARD"}},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/traverse-links",
headers={"Authorization": "Bearer <api key>"},
json={
"link": {"linkRid": "<link rid>", "direction": "LINK_DIRECTION_FORWARD"},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"edges": [
{
"requestedAssetRid": "<requested asset rid>",
"linkedAssetRid": "<linked asset rid>"
}
],
"nextPageToken": "<next page token>"
}
Update asset#
PUT /asset/v2/assets/{assetRid}
Updates an existing asset’s metadata.
Path parameters
assetRidstring required
Body
titlestring
descriptionstring
propertiesPropertyUpdateWrapperdeprecatedproperties/labels/links/data_scopes/types are tri-state: an absent wrapper leaves the value untouched; a present wrapper (even with an empty collection) replaces the value. Properties and labels reuse the shared nominal.types update wrappers (the same types the other conversions use); links, data scopes, and types have no shared wrapper, so they carry asset-local ones.
Fields of
PropertyUpdateWrapperpropertiesmap of string to string
labelsLabelUpdateWrapper
Fields of
LabelUpdateWrapperlabelsarray of string
linksLinkList
Fields of
LinkListlinksarray ofLink
Fields of
Linktitlestring
urlstring
dataScopesCreateAssetDataScopeListThe data scopes for the asset. When present, replaces all existing data scopes with the scopes specified.
Fields of
CreateAssetDataScopeListdataScopesarray ofCreateAssetDataScope
Fields of
CreateAssetDataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields required
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
isStagedboolean
typedPropertiesTypedPropertyUpdateWrapper
Fields of
TypedPropertyUpdateWrappertypedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValuerequired
stringValuestring
numericValuenumber
- one of
typesTypeRidListAbsent leaves memberships unchanged. Present, including empty, replaces them.
Fields of
TypeRidListtypesarray of stringAt most 10 types. Empty replaces memberships with none. At most 10 items.
dataAssetDataAbsent leaves the asset’s data unchanged. Present relinks the asset to this pipeline or raw dataset, on the same conditions as CreateAssetRequest.data, and checks every type the asset will have against it. Mutually exclusive with nonempty data_scopes. An asset with data scopes is relinked only when data_scopes is present and empty, which clears them; the caller must be able to read each scope’s data source. The pipeline or dataset the asset read before, including one built from its scopes, is left unchanged.
Fields of
AssetData- one of
pipelineRid,datasetRidrequired
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
Response
assetAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
Request
curl -X PUT "https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"title": "<title>",
"description": "<description>",
"properties": {
"properties": {
"<key>": "<value>"
}
},
"labels": {
"labels": [
"<labels>"
]
},
"links": {
"links": [
{
"title": "<title>",
"url": "<url>"
}
]
},
"dataScopes": {
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"seriesTags": {
"<key>": "<value>"
}
}
]
},
"isStaged": true,
"typedProperties": {
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
}
},
"types": {
"types": [
"<types>"
]
},
"data": {
"pipelineRid": "<pipeline rid>"
}
}'
import requests
response = requests.put(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>",
headers={"Authorization": "Bearer <api key>"},
json={
"title": "<title>",
"description": "<description>",
"properties": {"properties": {"<key>": "<value>"}},
"labels": {"labels": ["<labels>"]},
"links": {"links": [{"title": "<title>", "url": "<url>"}]},
"dataScopes": {
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
},
"isStaged": True,
"typedProperties": {
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
},
"types": {"types": ["<types>"]},
"data": {"pipelineRid": "<pipeline rid>"},
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.put(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>",
headers={"Authorization": "Bearer <api key>"},
json={
"title": "<title>",
"description": "<description>",
"properties": {"properties": {"<key>": "<value>"}},
"labels": {"labels": ["<labels>"]},
"links": {"links": [{"title": "<title>", "url": "<url>"}]},
"dataScopes": {
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
},
"isStaged": True,
"typedProperties": {
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
},
"types": {"types": ["<types>"]},
"data": {"pipelineRid": "<pipeline rid>"},
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.put(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>",
headers={"Authorization": "Bearer <api key>"},
json={
"title": "<title>",
"description": "<description>",
"properties": {"properties": {"<key>": "<value>"}},
"labels": {"labels": ["<labels>"]},
"links": {"links": [{"title": "<title>", "url": "<url>"}]},
"dataScopes": {
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
},
"isStaged": True,
"typedProperties": {
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
},
"types": {"types": ["<types>"]},
"data": {"pipelineRid": "<pipeline rid>"},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"asset": {
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
}
}
Archive#
POST /asset/v2/assets/{assetRid}/archive
Archives the asset with the given RID.
Path parameters
assetRidstring required
Body
includeLinkedWorkbooksbooleanIf true, all workbooks that are linked to the asset and associated runs will be archived as well. Defaults to false.
Response
An empty JSON object, {}.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/archive" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"includeLinkedWorkbooks": true
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/archive",
headers={"Authorization": "Bearer <api key>"},
json={"includeLinkedWorkbooks": True},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/archive",
headers={"Authorization": "Bearer <api key>"},
json={"includeLinkedWorkbooks": True},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/archive",
headers={"Authorization": "Bearer <api key>"},
json={"includeLinkedWorkbooks": True},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Update asset attachments#
POST /asset/v2/assets/{assetRid}/attachments
Update the attachments associated with an asset.
Path parameters
assetRidstring required
Body
attachmentsToAddarray of string
attachmentsToRemovearray of string
Response
An empty JSON object, {}.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/attachments" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"attachmentsToAdd": [
"<attachments to add>"
],
"attachmentsToRemove": [
"<attachments to remove>"
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/attachments",
headers={"Authorization": "Bearer <api key>"},
json={
"attachmentsToAdd": ["<attachments to add>"],
"attachmentsToRemove": ["<attachments to remove>"],
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/attachments",
headers={"Authorization": "Bearer <api key>"},
json={
"attachmentsToAdd": ["<attachments to add>"],
"attachmentsToRemove": ["<attachments to remove>"],
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/attachments",
headers={"Authorization": "Bearer <api key>"},
json={
"attachmentsToAdd": ["<attachments to add>"],
"attachmentsToRemove": ["<attachments to remove>"],
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Add data scopes to asset#
POST /asset/v2/assets/{assetRid}/data-scopes
Adds data scopes to an asset.
Throws if the asset already has data scopes with data scope names matching those in the request.
Path parameters
assetRidstring required
Body
dataScopesarray ofCreateAssetDataScopeThe data scopes to add to the asset. Throws if any existing data scopes have data scope names that conflict with the data scope names in the request.
Fields of
CreateAssetDataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields required
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
Response
assetAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/data-scopes" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"seriesTags": {
"<key>": "<value>"
}
}
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/data-scopes",
headers={"Authorization": "Bearer <api key>"},
json={
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/data-scopes",
headers={"Authorization": "Bearer <api key>"},
json={
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/data-scopes",
headers={"Authorization": "Bearer <api key>"},
json={
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"asset": {
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
}
}
Update asset ref names#
POST /asset/v2/assets/{assetRid}/ref-names
Update the ref names for the data scopes on the asset. This update will also be applied on all associated workbooks.
Path parameters
assetRidstring required
Body
dataScopeRefNameUpdatesmap of string to string
Response
An empty JSON object, {}.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/ref-names" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"dataScopeRefNameUpdates": {
"<key>": "<value>"
}
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/ref-names",
headers={"Authorization": "Bearer <api key>"},
json={"dataScopeRefNameUpdates": {"<key>": "<value>"}},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/ref-names",
headers={"Authorization": "Bearer <api key>"},
json={"dataScopeRefNameUpdates": {"<key>": "<value>"}},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/ref-names",
headers={"Authorization": "Bearer <api key>"},
json={"dataScopeRefNameUpdates": {"<key>": "<value>"}},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Unarchive#
POST /asset/v2/assets/{assetRid}/unarchive
Unarchives the asset with the given RID.
Path parameters
assetRidstring required
Body
includeLinkedWorkbooksbooleanIf true, all auto-archived workbooks that are linked to the asset and associated runs will be unarchived as well. Defaults to false.
Response
An empty JSON object, {}.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/unarchive" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"includeLinkedWorkbooks": true
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/unarchive",
headers={"Authorization": "Bearer <api key>"},
json={"includeLinkedWorkbooks": True},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/unarchive",
headers={"Authorization": "Bearer <api key>"},
json={"includeLinkedWorkbooks": True},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/assets/<asset rid>/unarchive",
headers={"Authorization": "Bearer <api key>"},
json={"includeLinkedWorkbooks": True},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Create type#
POST /asset/v2/types
Creates a new type.
Body
namestring
propertyConfigsmap of string toPropertyConfig
Fields of
PropertyConfigrequirementPropertyRequirement
Values of
PropertyRequirementPROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
valueTypePropertyValueType
Values of
PropertyValueTypePROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
descriptionstring
iconNamestring
workspacestringThe workspace in which to create the asset type. If not provided, the asset type will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured.
primaryKeystringThe property that identifies an asset of this type. It is a required nonempty string and is not repeated in property_configs.
dataRequirementsDataRequirementsRequirements on the data of assets of this type.
Fields of
DataRequirementsseriesSeriesRequirements
Fields of
SeriesRequirementsseriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
linksarray ofLinkDefinitionA link to the new type itself can only be added by a later update, once the type has a rid. At most 20 items.
Fields of
LinkDefinitionridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
Fields of
DirectLinksourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
Response
typeType
Fields of
Typeridstring
namestring
descriptionstring
propertyConfigsmap of string toPropertyConfig
Fields of
PropertyConfigrequirementPropertyRequirement
Values of
PropertyRequirementPROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
valueTypePropertyValueType
Values of
PropertyValueTypePROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
createdAtstring (date-time)
iconNamestringThe name of the icon to display for the type. This name maps to a Lucide icon in the frontend.
primaryKeystringThe property that identifies an asset of this type. It is a required nonempty string and is not repeated in property_configs.
isArchivedboolean
dataRequirementsDataRequirementsRequirements on the data of assets of this type, absent if none were ever set. Checked when the type is attached to an asset; later data or definition changes are not rechecked.
Fields of
DataRequirementsseriesSeriesRequirements
Fields of
SeriesRequirementsseriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
outgoingLinksarray ofLinkDefinitionLinks this type declares, oldest first.
Fields of
LinkDefinitionridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
Fields of
DirectLinksourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
incomingLinksarray ofLinkDefinitionLinks other types declare that target this type, including this type’s links to itself, oldest first. Read-only: a link is changed through its source type.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/types" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"name": "<name>",
"propertyConfigs": {
"<key>": {
"requirement": "REQUIRED",
"valueType": "STRING"
}
},
"description": "<description>",
"iconName": "<icon name>",
"workspace": "<workspace>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {
"series": [
{
"name": "<name>",
"type": "NUMERIC"
}
]
}
},
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/types",
headers={"Authorization": "Bearer <api key>"},
json={
"name": "<name>",
"propertyConfigs": {"<key>": {"requirement": "REQUIRED", "valueType": "STRING"}},
"description": "<description>",
"iconName": "<icon name>",
"workspace": "<workspace>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {"series": [{"name": "<name>", "type": "NUMERIC"}]},
},
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {"sourceProperty": "<source property>"},
},
],
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/types",
headers={"Authorization": "Bearer <api key>"},
json={
"name": "<name>",
"propertyConfigs": {"<key>": {"requirement": "REQUIRED", "valueType": "STRING"}},
"description": "<description>",
"iconName": "<icon name>",
"workspace": "<workspace>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {"series": [{"name": "<name>", "type": "NUMERIC"}]},
},
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {"sourceProperty": "<source property>"},
},
],
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/types",
headers={"Authorization": "Bearer <api key>"},
json={
"name": "<name>",
"propertyConfigs": {
"<key>": {"requirement": "REQUIRED", "valueType": "STRING"},
},
"description": "<description>",
"iconName": "<icon name>",
"workspace": "<workspace>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {"series": [{"name": "<name>", "type": "NUMERIC"}]},
},
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {"sourceProperty": "<source property>"},
},
],
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"type": {
"rid": "<rid>",
"name": "<name>",
"description": "<description>",
"propertyConfigs": {
"<key>": {
"requirement": "REQUIRED",
"valueType": "STRING"
}
},
"createdAt": "2026-01-01T00:00:00Z",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"isArchived": true,
"dataRequirements": {
"series": {
"series": [
{
"name": "<name>",
"type": "NUMERIC"
}
]
}
},
"outgoingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
],
"incomingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
]
}
}
Get types#
POST /asset/v2/types/batch-get
Returns the asset types for the given type RIDs.
Body
ridsarray of string
Response
responsesmap of string toType
Fields of
Typeridstring
namestring
descriptionstring
propertyConfigsmap of string toPropertyConfig
Fields of
PropertyConfigrequirementPropertyRequirement
Values of
PropertyRequirementPROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
valueTypePropertyValueType
Values of
PropertyValueTypePROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
createdAtstring (date-time)
iconNamestringThe name of the icon to display for the type. This name maps to a Lucide icon in the frontend.
primaryKeystringThe property that identifies an asset of this type. It is a required nonempty string and is not repeated in property_configs.
isArchivedboolean
dataRequirementsDataRequirementsRequirements on the data of assets of this type, absent if none were ever set. Checked when the type is attached to an asset; later data or definition changes are not rechecked.
Fields of
DataRequirementsseriesSeriesRequirements
Fields of
SeriesRequirementsseriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
outgoingLinksarray ofLinkDefinitionLinks this type declares, oldest first.
Fields of
LinkDefinitionridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
Fields of
DirectLinksourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
incomingLinksarray ofLinkDefinitionLinks other types declare that target this type, including this type’s links to itself, oldest first. Read-only: a link is changed through its source type.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/types/batch-get" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"rids": [
"<rids>"
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/types/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/types/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/types/batch-get",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"responses": {
"<key>": {
"rid": "<rid>",
"name": "<name>",
"description": "<description>",
"propertyConfigs": {
"<key>": {
"requirement": "REQUIRED",
"valueType": "STRING"
}
},
"createdAt": "2026-01-01T00:00:00Z",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"isArchived": true,
"dataRequirements": {
"series": {
"series": [
{
"name": "<name>",
"type": "NUMERIC"
}
]
}
},
"outgoingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
],
"incomingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
]
}
}
}
Search types#
POST /asset/v2/types/search
Searches for asset types matching the given query.
Body
sortTypeSortOptions
Fields of
TypeSortOptionsisDescendingboolean
fieldTypeSortField
Values of
TypeSortFieldTYPE_SORT_FIELD_UNSPECIFIED
CREATED_AT
pageSizeintegerPage sizes greater than 10_000 will be rejected. Default pageSize is 100.
nextPageTokenstring
querySearchTypesQuery
Fields of
SearchTypesQuery- one of 5 fields required
searchTextstring
propertystring
andSearchTypesQueryList
Fields of
SearchTypesQueryListqueriesarray ofSearchTypesQuery
workspacestring
archivedStatusesArchivedStatusSet
Fields of
ArchivedStatusSetarchivedStatusesarray ofArchivedStatus
Values of
ArchivedStatusARCHIVED_STATUS_UNSPECIFIED
NOT_ARCHIVED
ARCHIVED
Response
resultsarray ofType
Fields of
Typeridstring
namestring
descriptionstring
propertyConfigsmap of string toPropertyConfig
Fields of
PropertyConfigrequirementPropertyRequirement
Values of
PropertyRequirementPROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
valueTypePropertyValueType
Values of
PropertyValueTypePROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
createdAtstring (date-time)
iconNamestringThe name of the icon to display for the type. This name maps to a Lucide icon in the frontend.
primaryKeystringThe property that identifies an asset of this type. It is a required nonempty string and is not repeated in property_configs.
isArchivedboolean
dataRequirementsDataRequirementsRequirements on the data of assets of this type, absent if none were ever set. Checked when the type is attached to an asset; later data or definition changes are not rechecked.
Fields of
DataRequirementsseriesSeriesRequirements
Fields of
SeriesRequirementsseriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
outgoingLinksarray ofLinkDefinitionLinks this type declares, oldest first.
Fields of
LinkDefinitionridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
Fields of
DirectLinksourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
incomingLinksarray ofLinkDefinitionLinks other types declare that target this type, including this type’s links to itself, oldest first. Read-only: a link is changed through its source type.
nextPageTokenstring
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/types/search" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"sort": {
"isDescending": true,
"field": "CREATED_AT"
},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {
"searchText": "<search text>"
},
"archivedStatuses": {
"archivedStatuses": [
"NOT_ARCHIVED"
]
}
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/types/search",
headers={"Authorization": "Bearer <api key>"},
json={
"sort": {"isDescending": True, "field": "CREATED_AT"},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {"searchText": "<search text>"},
"archivedStatuses": {"archivedStatuses": ["NOT_ARCHIVED"]},
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/types/search",
headers={"Authorization": "Bearer <api key>"},
json={
"sort": {"isDescending": True, "field": "CREATED_AT"},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {"searchText": "<search text>"},
"archivedStatuses": {"archivedStatuses": ["NOT_ARCHIVED"]},
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/types/search",
headers={"Authorization": "Bearer <api key>"},
json={
"sort": {"isDescending": True, "field": "CREATED_AT"},
"pageSize": 1,
"nextPageToken": "<next page token>",
"query": {"searchText": "<search text>"},
"archivedStatuses": {"archivedStatuses": ["NOT_ARCHIVED"]},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"results": [
{
"rid": "<rid>",
"name": "<name>",
"description": "<description>",
"propertyConfigs": {
"<key>": {
"requirement": "REQUIRED",
"valueType": "STRING"
}
},
"createdAt": "2026-01-01T00:00:00Z",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"isArchived": true,
"dataRequirements": {
"series": {
"series": [
{
"name": "<name>",
"type": "NUMERIC"
}
]
}
},
"outgoingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
],
"incomingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
]
}
],
"nextPageToken": "<next page token>"
}
Delete type#
DELETE /asset/v2/types/{typeRid}
Deletes a type. The type must not be referenced by any assets.
Path parameters
typeRidstring required
Response
An empty JSON object, {}.
Request
curl -X DELETE "https://api.gov.nominal.io/api/asset/v2/types/<type rid>" \
-H "Authorization: Bearer <api key>"
import requests
response = requests.delete(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.delete(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.delete(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>",
headers={"Authorization": "Bearer <api key>"},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Update type#
PUT /asset/v2/types/{typeRid}
Updates a type. Will throw unless all assets that reference the type pass the updated type check.
Path parameters
typeRidstring required
Body
namestring
propertyConfigsPropertyConfigMapTri-state: an absent wrapper leaves the value untouched; a present wrapper replaces it.
Fields of
PropertyConfigMappropertyConfigsmap of string toPropertyConfig
Fields of
PropertyConfigrequirementPropertyRequirement
Values of
PropertyRequirementPROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
valueTypePropertyValueType
Values of
PropertyValueTypePROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
descriptionstring
iconNamestring
primaryKeystring
dataRequirementsDataRequirementsAbsent leaves the requirements unchanged. Present replaces them; requiring no series clears them. Assets that already have the type are not rechecked, unlike property_configs, which every such asset must still satisfy.
Fields of
DataRequirementsseriesSeriesRequirements
Fields of
SeriesRequirementsseriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
linksLinkDefinitionListAbsent leaves the links unchanged. Present replaces the type’s outgoing links: an entry with a rid keeps that link and replaces its labels, an entry without one adds a link, and an existing link whose rid is left out is removed. A type’s outgoing_links can be sent back as read. Present property configs must still declare every remaining link’s property as a string.
Fields of
LinkDefinitionListlinksarray ofLinkDefinitionAt most 20 items.
Fields of
LinkDefinitionridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
Fields of
DirectLinksourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
Response
typeType
Fields of
Typeridstring
namestring
descriptionstring
propertyConfigsmap of string toPropertyConfig
Fields of
PropertyConfigrequirementPropertyRequirement
Values of
PropertyRequirementPROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
valueTypePropertyValueType
Values of
PropertyValueTypePROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
createdAtstring (date-time)
iconNamestringThe name of the icon to display for the type. This name maps to a Lucide icon in the frontend.
primaryKeystringThe property that identifies an asset of this type. It is a required nonempty string and is not repeated in property_configs.
isArchivedboolean
dataRequirementsDataRequirementsRequirements on the data of assets of this type, absent if none were ever set. Checked when the type is attached to an asset; later data or definition changes are not rechecked.
Fields of
DataRequirementsseriesSeriesRequirements
Fields of
SeriesRequirementsseriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
Fields of
SeriesRequirementnamestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
Values of
SeriesTypeSERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
outgoingLinksarray ofLinkDefinitionLinks this type declares, oldest first.
Fields of
LinkDefinitionridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
Fields of
DirectLinksourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
incomingLinksarray ofLinkDefinitionLinks other types declare that target this type, including this type’s links to itself, oldest first. Read-only: a link is changed through its source type.
Request
curl -X PUT "https://api.gov.nominal.io/api/asset/v2/types/<type rid>" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"name": "<name>",
"propertyConfigs": {
"propertyConfigs": {
"<key>": {
"requirement": "REQUIRED",
"valueType": "STRING"
}
}
},
"description": "<description>",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {
"series": [
{
"name": "<name>",
"type": "NUMERIC"
}
]
}
},
"links": {
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
]
}
}'
import requests
response = requests.put(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>",
headers={"Authorization": "Bearer <api key>"},
json={
"name": "<name>",
"propertyConfigs": {
"propertyConfigs": {
"<key>": {"requirement": "REQUIRED", "valueType": "STRING"},
},
},
"description": "<description>",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {"series": [{"name": "<name>", "type": "NUMERIC"}]},
},
"links": {
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {"sourceProperty": "<source property>"},
},
],
},
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.put(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>",
headers={"Authorization": "Bearer <api key>"},
json={
"name": "<name>",
"propertyConfigs": {
"propertyConfigs": {
"<key>": {"requirement": "REQUIRED", "valueType": "STRING"},
},
},
"description": "<description>",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {"series": [{"name": "<name>", "type": "NUMERIC"}]},
},
"links": {
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {"sourceProperty": "<source property>"},
},
],
},
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.put(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>",
headers={"Authorization": "Bearer <api key>"},
json={
"name": "<name>",
"propertyConfigs": {
"propertyConfigs": {
"<key>": {"requirement": "REQUIRED", "valueType": "STRING"},
},
},
"description": "<description>",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"dataRequirements": {
"series": {"series": [{"name": "<name>", "type": "NUMERIC"}]},
},
"links": {
"links": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {"sourceProperty": "<source property>"},
},
],
},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"type": {
"rid": "<rid>",
"name": "<name>",
"description": "<description>",
"propertyConfigs": {
"<key>": {
"requirement": "REQUIRED",
"valueType": "STRING"
}
},
"createdAt": "2026-01-01T00:00:00Z",
"iconName": "<icon name>",
"primaryKey": "<primary key>",
"isArchived": true,
"dataRequirements": {
"series": {
"series": [
{
"name": "<name>",
"type": "NUMERIC"
}
]
}
},
"outgoingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
],
"incomingLinks": [
{
"rid": "<rid>",
"sourceTypeRid": "<source type rid>",
"targetTypeRid": "<target type rid>",
"forwardLabel": "<forward label>",
"inverseLabel": "<inverse label>",
"direct": {
"sourceProperty": "<source property>"
}
}
]
}
}
Archive type#
POST /asset/v2/types/{typeRid}/archive
Archives the asset type with the given RID.
Path parameters
typeRidstring required
Response
An empty JSON object, {}.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/types/<type rid>/archive" \
-H "Authorization: Bearer <api key>"
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/archive",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/archive",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/archive",
headers={"Authorization": "Bearer <api key>"},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Create or update asset by primary key#
POST /asset/v2/types/{typeRid}/assets
Creates an asset identified by a type and its primary-key value, or resolves the active asset that already has that identity. Archived assets are ignored, so a key held only by an archived asset creates a new asset. Concurrent calls with the same identity resolve to one asset. Needs create permission in the workspace. Returning or updating an existing asset needs view permission on it, otherwise the call fails with AssetPermissionDenied; updating it also needs edit permission.
Path parameters
typeRidstring requiredThe type whose primary key identifies the asset. Must be listed in asset.types.
Body
assetCreateAssetRequestrequiredThe asset to create. Must set the type’s primary-key property to a nonempty string.
Fields of
CreateAssetRequesttitlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of string
linksarray ofLink
Fields of
Linktitlestring
urlstring
dataScopesarray ofCreateAssetDataScopeThe data scopes associated with the asset.
Fields of
CreateAssetDataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields required
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
attachmentsarray of string
workspacestringThe workspace in which to create the asset. If not provided, the asset will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured. All data scopes, attachments, and asset types must be in the same workspace.
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValuerequired
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. Mutually exclusive with data and nonempty data_scopes. Must be readable and in the asset’s workspace. Composition datasets attach directly and cannot already back an asset. Raw datasets are wrapped in a new pipeline without changing the source, so the response’s data may differ from this RID. At least 1 character.
typesarray of stringTypes to attach. Empty attaches none. At most 10 types. At most 10 items.
dataAssetDataThe pipeline or raw dataset the asset reads. Mutually exclusive with dataset_rid and nonempty data_scopes; omit all three for scope-based creation. The caller must be able to view it, and it must be unarchived, in the asset’s workspace, and not already read by another asset.
Fields of
AssetData- one of
pipelineRid,datasetRidrequired
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
ifExistsIfAssetExists
Values of
IfAssetExistsIF_ASSET_EXISTS_UNSPECIFIED
RETURN_EXISTINGReturn the existing asset unchanged.
UPDATE_EXISTINGReplace the existing asset’s title, description, properties, labels, links, and types with the request’s values, and its data scopes unless the request sets dataset_rid or data. Attachments, the asset’s data, the workspace, and the primary key are unchanged.
Response
assetAsset
Fields of
Assetridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
Fields of
Linktitlestring
urlstring
dataScopesarray ofDataScopeThe data scopes associated with the asset.
Fields of
DataScopedataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
Fields of
DataSource- one of 5 fields
datasetstring
connectionstring
logSetstring
videostring
spatialstring
offsetDuration
Fields of
Durationsecondsstring (int64)
nanosstring (int64)
timestampTypeWeakTimestampType
Values of
WeakTimestampTypeWEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
Fields of
TypedPropertyValue- one of
stringValue,numericValue
stringValuestring
numericValuenumber
- one of
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
Fields of
AssetData- one of
pipelineRid,datasetRid
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
- one of
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
createdbooleanTrue when this call created the asset. False when it returned or updated an existing one.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/types/<type rid>/assets" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"asset": {
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"seriesTags": {
"<key>": "<value>"
}
}
],
"attachments": [
"<attachments>"
],
"workspace": "<workspace>",
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"types": [
"<types>"
],
"data": {
"pipelineRid": "<pipeline rid>"
}
}
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/assets",
headers={"Authorization": "Bearer <api key>"},
json={
"asset": {
"title": "<title>",
"description": "<description>",
"properties": {"<key>": "<value>"},
"labels": ["<labels>"],
"links": [{"title": "<title>", "url": "<url>"}],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
"attachments": ["<attachments>"],
"workspace": "<workspace>",
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
"datasetRid": "<dataset rid>",
"types": ["<types>"],
"data": {"pipelineRid": "<pipeline rid>"},
},
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/assets",
headers={"Authorization": "Bearer <api key>"},
json={
"asset": {
"title": "<title>",
"description": "<description>",
"properties": {"<key>": "<value>"},
"labels": ["<labels>"],
"links": [{"title": "<title>", "url": "<url>"}],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
"attachments": ["<attachments>"],
"workspace": "<workspace>",
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
"datasetRid": "<dataset rid>",
"types": ["<types>"],
"data": {"pipelineRid": "<pipeline rid>"},
},
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/assets",
headers={"Authorization": "Bearer <api key>"},
json={
"asset": {
"title": "<title>",
"description": "<description>",
"properties": {"<key>": "<value>"},
"labels": ["<labels>"],
"links": [{"title": "<title>", "url": "<url>"}],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {"dataset": "<dataset>"},
"offset": {"seconds": "1", "nanos": "1"},
"seriesTags": {"<key>": "<value>"},
},
],
"attachments": ["<attachments>"],
"workspace": "<workspace>",
"typedProperties": {"<key>": {"stringValue": "<string value>"}},
"datasetRid": "<dataset rid>",
"types": ["<types>"],
"data": {"pipelineRid": "<pipeline rid>"},
},
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"asset": {
"rid": "<rid>",
"title": "<title>",
"description": "<description>",
"properties": {
"<key>": "<value>"
},
"labels": [
"<labels>"
],
"links": [
{
"title": "<title>",
"url": "<url>"
}
],
"dataScopes": [
{
"dataScopeName": "<data scope name>",
"dataSource": {
"dataset": "<dataset>"
},
"offset": {
"seconds": "1",
"nanos": "1"
},
"timestampType": "ABSOLUTE",
"seriesTags": {
"<key>": "<value>"
}
}
],
"createdBy": "<created by>",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"attachments": [
"<attachments>"
],
"types": [
"<types>"
],
"isStaged": true,
"isArchived": true,
"typedProperties": {
"<key>": {
"stringValue": "<string value>"
}
},
"datasetRid": "<dataset rid>",
"isLive": true,
"data": {
"pipelineRid": "<pipeline rid>"
},
"iconName": "<icon name>"
},
"created": true
}
Unarchive type#
POST /asset/v2/types/{typeRid}/unarchive
Unarchives the asset type with the given RID.
Path parameters
typeRidstring required
Response
An empty JSON object, {}.
Request
curl -X POST "https://api.gov.nominal.io/api/asset/v2/types/<type rid>/unarchive" \
-H "Authorization: Bearer <api key>"
import requests
response = requests.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/unarchive",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/unarchive",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/asset/v2/types/<type rid>/unarchive",
headers={"Authorization": "Bearer <api key>"},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{}
Errors#
Errors shows how these errors are sent.
Each error’s errorName is NominalAssetV2: followed by its name below.
Status |
Name |
Notes |
|---|---|---|
400 |
|
InvalidAssetRequest |
403 |
|
AssetPermissionDenied |
404 |
|
LinkNotFound |
Types#
ArchivedStatus#
ARCHIVED_STATUS_UNSPECIFIED
NOT_ARCHIVED
ARCHIVED
ArchivedStatusSet#
archivedStatusesarray ofArchivedStatus
Asset#
ridstring
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of stringLabels associated with the asset. These labels do not have a time dimension. To associate labels with a range of time, create a time range on the asset with labels.
linksarray ofLinkLinks associated with the asset. These links do not have a time dimension. To associate links with a range of time, create a time range on the asset with links.
dataScopesarray ofDataScopeThe data scopes associated with the asset.
createdBystring
createdAtstring (date-time)
updatedAtstring (date-time)
attachmentsarray of string
typesarray of stringTypes attached to the asset. At most 10.
isStagedbooleanAuto created assets are considered staged by default.
isArchivedboolean
typedPropertiesmap of string toTypedPropertyValue
datasetRidstring deprecatedDeprecated: use data. The dataset form of data’s uuid, which resolves to the pipeline or raw dataset alike.
isLivebooleanWhether any of the asset’s datasets is receiving live data, as the
livesearch query defines it. Only SearchAssets and GetAssets set it; absent means not computed, not “not live”.dataAssetDataThe pipeline or raw dataset this asset reads. Absent for legacy assets without representable scopes.
iconNamestringA typed asset may have a representative lucide-icon that differs from the default icon for assets that we show in the UI. This is usually the icon of the first asset type of the types associated with the asset (alphabetical)
AssetData#
The pipeline or raw dataset an asset reads. Clients should treat an unset oneof as a kind added after they were built.
Set exactly one of the fields below.
- one of
pipelineRid,datasetRidrequired
pipelineRidstringA pipeline the asset reads as it changes. Editing the asset’s data scopes does not change it. At least 1 character.
datasetRidstringA raw catalog dataset the asset reads directly. Derived datasets are named by their pipeline instead. An asset reading a raw dataset has no data scopes to edit. At least 1 character.
AssetDataConformance#
How an asset’s current data meets the data requirements of its types.
typesmap of string toTypeDataConformanceKeyed by type RID, with an entry for each type on the asset that has data requirements.
AssetRidsFilter#
Matches assets whose RID is any of the provided RIDs. Composable with and/or/not, e.g. to intersect a known candidate set with label or property predicates. Rejects an empty list and lists of more than 1000 RIDs.
assetRidsarray of string1 to 1,000 items.
AssetSortField#
ASSET_SORT_FIELD_UNSPECIFIED
NAME
CREATED_AT
MOST_RECENT_RUN_START
AssetSortOptions#
isDescendingboolean
fieldAssetSortField
sortKeySortKeyField to sort by. Includes both field and property-based sorting. Must be supplied if field is not provided separately.
AssetTypesFilter#
Matches an asset when any of its types is in asset_types.
assetTypesarray of string
ConflictBehavior#
Controls what happens when a rename target property key already exists on a document.
Set exactly one of the fields below.
- one of
skip,overwriterequired
skipSkipOnConflict
overwriteOverwriteOnConflict
CreateAssetDataScope#
dataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
offsetDuration
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
CreateAssetDataScopeList#
dataScopesarray ofCreateAssetDataScope
CreateAssetRequest#
titlestring
descriptionstring
propertiesmap of string to string deprecated
labelsarray of string
linksarray ofLink
dataScopesarray ofCreateAssetDataScopeThe data scopes associated with the asset.
attachmentsarray of string
workspacestringThe workspace in which to create the asset. If not provided, the asset will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured. All data scopes, attachments, and asset types must be in the same workspace.
typedPropertiesmap of string toTypedPropertyValue
datasetRidstring deprecatedDeprecated: use data. Mutually exclusive with data and nonempty data_scopes. Must be readable and in the asset’s workspace. Composition datasets attach directly and cannot already back an asset. Raw datasets are wrapped in a new pipeline without changing the source, so the response’s data may differ from this RID. At least 1 character.
typesarray of stringTypes to attach. Empty attaches none. At most 10 types. At most 10 items.
dataAssetDataThe pipeline or raw dataset the asset reads. Mutually exclusive with dataset_rid and nonempty data_scopes; omit all three for scope-based creation. The caller must be able to view it, and it must be unarchived, in the asset’s workspace, and not already read by another asset.
DataRequirements#
The requirements on the data of assets of a type. Clients should treat an unset oneof as requirements they cannot display: it is a kind added after the client was built.
seriesSeriesRequirements
DataRequirementsMet#
The asset’s data meets the requirements.
An empty JSON object, {}.
DataRequirementsUnknown#
The requirements could not be checked, because the caller cannot read the asset’s data or looking the series up took too long.
An empty JSON object, {}.
DataRequirementsUnmet#
The asset’s data does not meet the requirements.
missingSeriesarray ofSeriesRequirementEvery required series that the asset’s data has no series of that name and type for, by name. Nonempty.
DataScope#
dataScopeNamestringThe name of the data scope. The name is guaranteed to be unique within the context of an asset.
dataSourceDataSource
offsetDuration
timestampTypeWeakTimestampType
seriesTagsmap of string to stringFilters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.
DataSource#
Set exactly one of the fields below.
- one of 5 fields required
datasetstring
connectionstring
logSetstring
videostring
spatialstring
DirectLink#
A source asset’s value for a string property references the active asset of the target type whose primary key equals it.
sourcePropertystringA string property declared in the source type’s property_configs, other than its primary key. Whether every source asset must set it is that property’s requirement. At least 1 character.
Duration#
secondsstring (int64)
nanosstring (int64)
IfAssetExists#
What CreateOrUpdateAssetByPrimaryKey does when an active asset already has the requested type and primary-key value.
IF_ASSET_EXISTS_UNSPECIFIED
RETURN_EXISTINGReturn the existing asset unchanged.
UPDATE_EXISTINGReplace the existing asset’s title, description, properties, labels, links, and types with the request’s values, and its data scopes unless the request sets dataset_rid or data. Attachments, the asset’s data, the workspace, and the primary key are unchanged.
LabelsFilter#
operatorSetOperator
labelsarray of string
LabelUpdateWrapper#
Wrapper classes to allow for optional fields on update requests
labelsarray of string
Link#
titlestring
urlstring
LinkDefinition#
A link from assets of the source type to assets of the target type. A link that matches no active asset is unresolved; references are never blocked from dangling. Deleting either type deletes the link.
Type create and update requests take the same message: the target type must be in the source type’s workspace, a new link needs both types to be unarchived, and a type cannot link the same property to the same target type twice. Existing links keep working when either type is archived later.
ridstringServer-assigned. In an update, names one of the type’s existing links, whose kind and target type cannot change; absent adds a new link. Must be absent on create.
sourceTypeRidstringRead-only: always present in responses. Leave it unset in requests, where the source is the type being created or updated; a value sent there is ignored.
targetTypeRidstringMay be the source type itself.
forwardLabelstringThe link’s name seen from the source type, absent if not set. Clients typically fall back to the target type’s name. 1 to 100 characters.
inverseLabelstringThe link’s name seen from the target type, absent if not set. Clients typically fall back to the source type’s name. 1 to 100 characters.
directDirectLink
LinkDefinitionList#
linksarray ofLinkDefinitionAt most 20 items.
LinkDirection#
LINK_DIRECTION_UNSPECIFIED
LINK_DIRECTION_FORWARDFrom assets of the link’s source type to the assets of its target type they link to.
LINK_DIRECTION_INVERSEFrom assets of the link’s target type to the assets of its source type that link to them.
LinkEdge#
One requested asset and what the link connects it to.
Set at most one of linkedAssetRid, unresolvedValue.
requestedAssetRidstring
- one of
linkedAssetRid,unresolvedValue
linkedAssetRidstringAn active asset at the other end of the link that the caller can view.
unresolvedValuestringForward on a direct link only: the source property’s string value when it names no active asset of the target type that the caller can view, including blank values and values longer than any primary key. An asset the caller cannot view is indistinguishable from a missing one. Absent properties produce no edge.
LinkList#
linksarray ofLink
LinkRef#
A link followed in one direction.
linkRidstring
directionLinkDirection
MergePropertyValuesForKey#
Merge one or more string values of a property key into a single target value. Merge applies to categorical aliases; continuous numeric values are intentionally excluded.
keystring
sourcearray of string
targetstring
MetadataChange#
Set exactly one of the fields below.
- one of
renameLabel,renamePropertyKey,mergePropertyValuesForKeyrequired
renameLabelRenameLabel
renamePropertyKeyRenamePropertyKey
mergePropertyValuesForKeyMergePropertyValuesForKey
NumericPropertyPredicate#
Matches resources that have a numeric value for the named property and whose value satisfies the operator. NEQ excludes resources that lack the property or store a string value under the same name.
namestring
valuenumber
operatorPropertyComparisonOperator
NumericPropertyRangeOperator#
NUMERIC_PROPERTY_RANGE_OPERATOR_UNSPECIFIED
BETWEEN
NOT_BETWEEN
NumericPropertyRangePredicate#
Inclusive range on a numeric property. At least one bound is required. BETWEEN: min <= x <= max. An absent bound is unbounded on that side. NOT_BETWEEN: x < min OR x > max. An absent bound drops that side. Both operators require a numeric value for name. Missing properties and string values never match. Bounds are closed [min, max] to match the number chip (is between / is not between), not half-open.
namestring
minnumber
maxnumber
operatorNumericPropertyRangeOperator
OverwriteOnConflict#
Documents that already have the target property key are included in the rename. The priority list determines which value wins via ordered precedence. Must contain exactly the source keys + target key.
priorityarray of string
PropertiesFilter#
namestring
valuesarray of string
Property#
namestring
valuestring
PropertyComparisonOperator#
PROPERTY_COMPARISON_OPERATOR_UNSPECIFIED
EQ
NEQ
GT
GTE
LT
LTE
PropertyConfig#
requirementPropertyRequirement
valueTypePropertyValueType
PropertyConfigMap#
propertyConfigsmap of string toPropertyConfig
PropertyRequirement#
PROPERTY_REQUIREMENT_UNSPECIFIED
REQUIRED
SUGGESTED
PropertyUpdateWrapper#
propertiesmap of string to string
PropertyValueType#
PROPERTY_VALUE_TYPE_UNSPECIFIED
STRING
NUMBER
RenameLabel#
Rename or merge one or more source labels into a single target label.
sourcearray of string
targetstring
RenamePropertyKey#
Rename one or more source property keys to a single target key. Existing values are preserved under the new key. The rename should be skipped in the service for resources w/ conflicting keys.
sourcearray of string
targetstring
onConflictConflictBehavior
SearchAssetsQuery#
Set exactly one of the fields below.
- one of 19 fields required
searchTextstring
exactSubstringstringA case-insensitive substring match of the title or description of the asset.
labelstring
labelsLabelsFilter
propertyProperty
propertyKeystringMatches assets that have a property with this key, regardless of value.
propertiesPropertiesFilter
typeRidstring
assetTypesAssetTypesFilter
isStagedboolean
archivedboolean
notSearchAssetsQuery
workspacestring
numericPropertyNumericPropertyPredicate
numericPropertyRangeNumericPropertyRangePredicateMatches assets using an inclusive numeric property range.
assetRidsAssetRidsFilterMatches assets whose RID is any of the provided RIDs.
livebooleanMatches assets with any dataset currently receiving live data.
SearchAssetsQueryList#
queriesarray ofSearchAssetsQuery
SearchTypesQuery#
Set exactly one of the fields below.
- one of 5 fields required
SearchTypesQueryList#
queriesarray ofSearchTypesQuery
SeriesRequirement#
namestringA channel name of 1 to 200 characters, matched exactly. 1 to 200 characters.
typeSeriesType
SeriesRequirements#
Met when, for each required series, the asset’s data has a series with that exact name and type under the data scopes’ tag filters, at any time. No series requires nothing, which is how an update clears the requirements.
seriesarray ofSeriesRequirementAt most 200, with unique names. At most 200 items.
SeriesType#
The kind of a required series. A series of any stored type within the kind satisfies the requirement. Nested so its STRING value does not collide with PropertyValueType.STRING at package scope (proto enum values are siblings of their enclosing scope).
SERIES_TYPE_UNSPECIFIED
NUMERICDouble, int64 or uint64 points.
STRING
LOG
NUMERIC_ARRAY
STRING_ARRAY
STRUCT
SetOperator#
SET_OPERATOR_UNSPECIFIED
AND
OR
SkipOnConflict#
Documents are skipped when: - The target property key already exists on the document, or - Multiple source property keys exist on the document (ambiguous merge). Conflicting document RIDs are returned in the response.
An empty JSON object, {}.
SortKey#
Set exactly one of the fields below.
- one of
field,property,numericPropertyrequired
fieldAssetSortField
propertySortProperty
numericPropertySortPropertySorts numeric property values numerically. String-valued and missing properties are null and always sort last.
SortProperty#
namestring
Type#
ridstring
namestring
descriptionstring
propertyConfigsmap of string toPropertyConfig
createdAtstring (date-time)
iconNamestringThe name of the icon to display for the type. This name maps to a Lucide icon in the frontend.
primaryKeystringThe property that identifies an asset of this type. It is a required nonempty string and is not repeated in property_configs.
isArchivedboolean
dataRequirementsDataRequirementsRequirements on the data of assets of this type, absent if none were ever set. Checked when the type is attached to an asset; later data or definition changes are not rechecked.
outgoingLinksarray ofLinkDefinitionLinks this type declares, oldest first.
incomingLinksarray ofLinkDefinitionLinks other types declare that target this type, including this type’s links to itself, oldest first. Read-only: a link is changed through its source type.
TypeDataConformance#
How an asset’s current data meets one type’s data_requirements.
Set at most one of the fields below.
- one of
met,unmet,unknown
TypedPropertyUpdateWrapper#
typedPropertiesmap of string toTypedPropertyValue
TypedPropertyValue#
Set exactly one of the fields below.
- one of
stringValue,numericValuerequired
stringValuestring
numericValuenumber
TypeRidList#
typesarray of stringAt most 10 types. Empty replaces memberships with none. At most 10 items.
TypeSortField#
Nested so its CREATED_AT value does not collide with AssetSortField.CREATED_AT at package scope (proto enum values are siblings of their enclosing scope).
TYPE_SORT_FIELD_UNSPECIFIED
CREATED_AT
TypeSortOptions#
isDescendingboolean
fieldTypeSortField
WeakTimestampType#
If a CSV data source is still being split, the timestamp type is not yet known.
WEAK_TIMESTAMP_TYPE_UNSPECIFIED
ABSOLUTE
RELATIVE
PENDING
Page design based on Scalar, MIT License.