# Spatial asset service

The spatial asset service manages spatial assets (point clouds, etc.) and their metadata. Spatial asset data is stored in Dagger; Nominal tracks metadata and references.

OpenAPI file: [`SpatialService.json`](https://dev.nominal.io/api/_downloads/8ac41b88d5ab436d58aa607b722e4177/SpatialService.json)

## Endpoints

### Get

GET `/spatial/v1/spatials/{spatialRid}`

Returns spatial asset metadata associated with a spatial asset rid.

Path parameters

`spatialRid` string (RID) required
:   ​

Response

`rid` string (RID)
:   Unique resource identifier for this spatial asset.

`title` string
:   Human-readable name.

`description` string
:   Optional longer description.

`labels` array of string
:   Labels for categorization and filtering.

`properties` map of `PropertyName` to string
:   Arbitrary key-value metadata.

`createdBy` string (RID)
:   RID of the user who created this asset.

`createdAt` string (date-time)
:   When this asset was created.

`updatedAt` string (date-time)
:   When this asset was last modified.

`isArchived` boolean
:   Whether this asset has been archived.

`daggerUuid` string (UUID)
:   The UUID of the Dagger model containing this asset’s data. Supplied by the caller at create time.

`typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata)
:   Type-specific metadata (e.g. sensor metadata for point clouds). The variant of this union also serves as the type discriminator — there is no separate spatialType field.

    **pointCloud**

    Set `type` to `"pointCloud"`.

    `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
    :   ​

        Fields of `PointCloudMetadata`

        `sensorModel` string
        :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

        `coordinateSystem` string
        :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

        `resolutionMm` number
        :   Spatial resolution of the point cloud in millimeters.

        `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
        :   The scan pattern of the lidar sensor.

            Values of `ScanPattern`

            `ROTATING`
            :   ​

            `SOLID_STATE`
            :   ​

            `FLASH`
            :   ​

            `MECHANICAL`
            :   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   Start of the time range covered by this spatial asset.

    Fields of `Timestamp`

    `seconds` integer (int64)
    :   ​

    `nanos` integer (int64)
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   End of the time range covered by this spatial asset.

`sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
:   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

    **s3**

    Set `type` to `"s3"`.

    `s3` string
    :   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<spatial rid>",
  "title": "<title>",
  "description": "<description>",
  "labels": [
    "<label>"
  ],
  "properties": {
    "<key>": "<property value>"
  },
  "createdBy": "<created by>",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true,
  "daggerUuid": "<dagger uuid>",
  "typeMetadata": {
    "type": "pointCloud",
    "pointCloud": {
      "sensorModel": "<sensor model>",
      "coordinateSystem": "<coordinate system>",
      "resolutionMm": 1,
      "scanPattern": "ROTATING"
    }
  },
  "startTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "endTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "sourceHandle": {
    "type": "s3",
    "s3": "<s3 path>"
  }
}
```

### Update metadata

PUT `/spatial/v1/spatials/{spatialRid}`

Updates the metadata for a spatial asset associated with the given rid.

Path parameters

`spatialRid` string (RID) required
:   ​

Body

`title` string
:   ​

`description` string
:   ​

`labels` array of string
:   ​

`properties` map of `PropertyName` to string
:   ​

`typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata)
:   ​

    **pointCloud**

    Set `type` to `"pointCloud"`.

    `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
    :   ​

        Fields of `PointCloudMetadata`

        `sensorModel` string
        :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

        `coordinateSystem` string
        :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

        `resolutionMm` number
        :   Spatial resolution of the point cloud in millimeters.

        `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
        :   The scan pattern of the lidar sensor.

            Values of `ScanPattern`

            `ROTATING`
            :   ​

            `SOLID_STATE`
            :   ​

            `FLASH`
            :   ​

            `MECHANICAL`
            :   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   ​

    Fields of `Timestamp`

    `seconds` integer (int64) required
    :   ​

    `nanos` integer (int64) required
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   ​

`sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
:   ​

    **s3**

    Set `type` to `"s3"`.

    `s3` string
    :   ​

Response

`rid` string (RID)
:   Unique resource identifier for this spatial asset.

`title` string
:   Human-readable name.

`description` string
:   Optional longer description.

`labels` array of string
:   Labels for categorization and filtering.

`properties` map of `PropertyName` to string
:   Arbitrary key-value metadata.

`createdBy` string (RID)
:   RID of the user who created this asset.

`createdAt` string (date-time)
:   When this asset was created.

`updatedAt` string (date-time)
:   When this asset was last modified.

`isArchived` boolean
:   Whether this asset has been archived.

`daggerUuid` string (UUID)
:   The UUID of the Dagger model containing this asset’s data. Supplied by the caller at create time.

`typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata)
:   Type-specific metadata (e.g. sensor metadata for point clouds). The variant of this union also serves as the type discriminator — there is no separate spatialType field.

    **pointCloud**

    Set `type` to `"pointCloud"`.

    `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
    :   ​

        Fields of `PointCloudMetadata`

        `sensorModel` string
        :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

        `coordinateSystem` string
        :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

        `resolutionMm` number
        :   Spatial resolution of the point cloud in millimeters.

        `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
        :   The scan pattern of the lidar sensor.

            Values of `ScanPattern`

            `ROTATING`
            :   ​

            `SOLID_STATE`
            :   ​

            `FLASH`
            :   ​

            `MECHANICAL`
            :   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   Start of the time range covered by this spatial asset.

    Fields of `Timestamp`

    `seconds` integer (int64)
    :   ​

    `nanos` integer (int64)
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   End of the time range covered by this spatial asset.

`sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
:   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

    **s3**

    Set `type` to `"s3"`.

    `s3` string
    :   ​

Request

**curl**

```shell
curl -X PUT "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "<title>",
  "description": "<description>",
  "labels": [
    "<label>"
  ],
  "properties": {
    "<key>": "<property value>"
  },
  "typeMetadata": {
    "type": "pointCloud",
    "pointCloud": {
      "sensorModel": "<sensor model>",
      "coordinateSystem": "<coordinate system>",
      "resolutionMm": 1,
      "scanPattern": "ROTATING"
    }
  },
  "startTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "endTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "sourceHandle": {
    "type": "s3",
    "s3": "<s3 path>"
  }
}'
```

**requests**

```python
import requests

response = requests.put(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "title": "<title>",
        "description": "<description>",
        "labels": ["<label>"],
        "properties": {"<key>": "<property value>"},
        "typeMetadata": {
            "type": "pointCloud",
            "pointCloud": {
                "sensorModel": "<sensor model>",
                "coordinateSystem": "<coordinate system>",
                "resolutionMm": 1,
                "scanPattern": "ROTATING",
            },
        },
        "startTimestamp": {"seconds": 1, "nanos": 1},
        "endTimestamp": {"seconds": 1, "nanos": 1},
        "sourceHandle": {"type": "s3", "s3": "<s3 path>"},
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "title": "<title>",
        "description": "<description>",
        "labels": ["<label>"],
        "properties": {"<key>": "<property value>"},
        "typeMetadata": {
            "type": "pointCloud",
            "pointCloud": {
                "sensorModel": "<sensor model>",
                "coordinateSystem": "<coordinate system>",
                "resolutionMm": 1,
                "scanPattern": "ROTATING",
            },
        },
        "startTimestamp": {"seconds": 1, "nanos": 1},
        "endTimestamp": {"seconds": 1, "nanos": 1},
        "sourceHandle": {"type": "s3", "s3": "<s3 path>"},
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "title": "<title>",
                "description": "<description>",
                "labels": ["<label>"],
                "properties": {"<key>": "<property value>"},
                "typeMetadata": {
                    "type": "pointCloud",
                    "pointCloud": {
                        "sensorModel": "<sensor model>",
                        "coordinateSystem": "<coordinate system>",
                        "resolutionMm": 1,
                        "scanPattern": "ROTATING",
                    },
                },
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
                "sourceHandle": {"type": "s3", "s3": "<s3 path>"},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<spatial rid>",
  "title": "<title>",
  "description": "<description>",
  "labels": [
    "<label>"
  ],
  "properties": {
    "<key>": "<property value>"
  },
  "createdBy": "<created by>",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true,
  "daggerUuid": "<dagger uuid>",
  "typeMetadata": {
    "type": "pointCloud",
    "pointCloud": {
      "sensorModel": "<sensor model>",
      "coordinateSystem": "<coordinate system>",
      "resolutionMm": 1,
      "scanPattern": "ROTATING"
    }
  },
  "startTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "endTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "sourceHandle": {
    "type": "s3",
    "s3": "<s3 path>"
  }
}
```

### Batch get

POST `/spatial/v1/spatials/batchGet`

Returns spatial asset metadata for each given spatial asset rid.

Body

`spatialRids` array of string (RID)
:   ​

Response

`responses` array of [`Spatial`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatial)
:   ​

    Fields of `Spatial`

    `rid` string (RID)
    :   Unique resource identifier for this spatial asset.

    `title` string
    :   Human-readable name.

    `description` string
    :   Optional longer description.

    `labels` array of string
    :   Labels for categorization and filtering.

    `properties` map of `PropertyName` to string
    :   Arbitrary key-value metadata.

    `createdBy` string (RID)
    :   RID of the user who created this asset.

    `createdAt` string (date-time)
    :   When this asset was created.

    `updatedAt` string (date-time)
    :   When this asset was last modified.

    `isArchived` boolean
    :   Whether this asset has been archived.

    `daggerUuid` string (UUID)
    :   The UUID of the Dagger model containing this asset’s data. Supplied by the caller at create time.

    `typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata)
    :   Type-specific metadata (e.g. sensor metadata for point clouds). The variant of this union also serves as the type discriminator — there is no separate spatialType field.

        **pointCloud**

        Set `type` to `"pointCloud"`.

        `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
        :   ​

            Fields of `PointCloudMetadata`

            `sensorModel` string
            :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

            `coordinateSystem` string
            :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

            `resolutionMm` number
            :   Spatial resolution of the point cloud in millimeters.

            `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
            :   The scan pattern of the lidar sensor.

                Values of `ScanPattern`

                `ROTATING`
                :   ​

                `SOLID_STATE`
                :   ​

                `FLASH`
                :   ​

                `MECHANICAL`
                :   ​

    `startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
    :   Start of the time range covered by this spatial asset.

        Fields of `Timestamp`

        `seconds` integer (int64)
        :   ​

        `nanos` integer (int64)
        :   ​

    `endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
    :   End of the time range covered by this spatial asset.

    `sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
    :   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

        **s3**

        Set `type` to `"s3"`.

        `s3` string
        :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/spatial/v1/spatials/batchGet" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "spatialRids": [
    "<spatial rid>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/batchGet",
    headers={"Authorization": "Bearer <api key>"},
    json={"spatialRids": ["<spatial rid>"]},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/batchGet",
    headers={"Authorization": "Bearer <api key>"},
    json={"spatialRids": ["<spatial rid>"]},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/spatial/v1/spatials/batchGet",
            headers={"Authorization": "Bearer <api key>"},
            json={"spatialRids": ["<spatial rid>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "responses": [
    {
      "rid": "<spatial rid>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<label>"
      ],
      "properties": {
        "<key>": "<property value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true,
      "daggerUuid": "<dagger uuid>",
      "typeMetadata": {
        "type": "pointCloud",
        "pointCloud": {
          "sensorModel": "<sensor model>",
          "coordinateSystem": "<coordinate system>",
          "resolutionMm": 1,
          "scanPattern": "ROTATING"
        }
      },
      "startTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "endTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "sourceHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      }
    }
  ]
}
```

### Search

POST `/spatial/v1/spatials/search`

Returns metadata about spatial assets that match a given query.

Body

`query` [`SearchSpatialsQuery`](https://dev.nominal.io/api/rest/spatial-asset-service.md#searchspatialsquery) required
:   ​

    **searchText**

    Set `type` to `"searchText"`.

    `searchText` string
    :   ​

    **label**

    Set `type` to `"label"`.

    `label` string
    :   ​

    **property**

    Set `type` to `"property"`.

    `property` [`Property`](https://dev.nominal.io/api/rest/spatial-asset-service.md#property)
    :   ​

        Fields of `Property`

        `name` string required
        :   ​

        `value` string required
        :   ​

    **and**

    Set `type` to `"and"`.

    `and` array of [`SearchSpatialsQuery`](https://dev.nominal.io/api/rest/spatial-asset-service.md#searchspatialsquery)
    :   ​

    **or**

    Set `type` to `"or"`.

    `or` array of [`SearchSpatialsQuery`](https://dev.nominal.io/api/rest/spatial-asset-service.md#searchspatialsquery)
    :   ​

    **workspace**

    Set `type` to `"workspace"`.

    `workspace` string (RID)
    :   ​

    **spatialType**

    Set `type` to `"spatialType"`.

    `spatialType` [`SpatialType`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtype)
    :   ​

        Values of `SpatialType`

        `POINT_CLOUD`
        :   ​

`pageSize` integer
:   Defaults to 100. Will throw if larger than 1000.

`token` string
:   ​

`sortOptions` [`SortOptions`](https://dev.nominal.io/api/rest/spatial-asset-service.md#sortoptions) required
:   ​

    Fields of `SortOptions`

    `isDescending` boolean required
    :   ​

    `field` [`SortField`](https://dev.nominal.io/api/rest/spatial-asset-service.md#sortfield) required
    :   ​

        Values of `SortField`

        `CREATED_AT`
        :   ​

`archivedStatuses` array of [`ArchivedStatus`](https://dev.nominal.io/api/rest/spatial-asset-service.md#archivedstatus)
:   Default search status is NOT_ARCHIVED if none are provided.

    Values of `ArchivedStatus`

    `NOT_ARCHIVED`
    :   ​

    `ARCHIVED`
    :   ​

Response

`results` array of [`Spatial`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatial)
:   ​

    Fields of `Spatial`

    `rid` string (RID)
    :   Unique resource identifier for this spatial asset.

    `title` string
    :   Human-readable name.

    `description` string
    :   Optional longer description.

    `labels` array of string
    :   Labels for categorization and filtering.

    `properties` map of `PropertyName` to string
    :   Arbitrary key-value metadata.

    `createdBy` string (RID)
    :   RID of the user who created this asset.

    `createdAt` string (date-time)
    :   When this asset was created.

    `updatedAt` string (date-time)
    :   When this asset was last modified.

    `isArchived` boolean
    :   Whether this asset has been archived.

    `daggerUuid` string (UUID)
    :   The UUID of the Dagger model containing this asset’s data. Supplied by the caller at create time.

    `typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata)
    :   Type-specific metadata (e.g. sensor metadata for point clouds). The variant of this union also serves as the type discriminator — there is no separate spatialType field.

        **pointCloud**

        Set `type` to `"pointCloud"`.

        `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
        :   ​

            Fields of `PointCloudMetadata`

            `sensorModel` string
            :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

            `coordinateSystem` string
            :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

            `resolutionMm` number
            :   Spatial resolution of the point cloud in millimeters.

            `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
            :   The scan pattern of the lidar sensor.

                Values of `ScanPattern`

                `ROTATING`
                :   ​

                `SOLID_STATE`
                :   ​

                `FLASH`
                :   ​

                `MECHANICAL`
                :   ​

    `startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
    :   Start of the time range covered by this spatial asset.

        Fields of `Timestamp`

        `seconds` integer (int64)
        :   ​

        `nanos` integer (int64)
        :   ​

    `endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
    :   End of the time range covered by this spatial asset.

    `sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
    :   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

        **s3**

        Set `type` to `"s3"`.

        `s3` string
        :   ​

`nextPageToken` string
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/spatial/v1/spatials/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "query": {
    "type": "searchText",
    "searchText": "<search text>"
  },
  "sortOptions": {
    "isDescending": true,
    "field": "CREATED_AT"
  }
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"type": "searchText", "searchText": "<search text>"},
        "sortOptions": {"isDescending": True, "field": "CREATED_AT"},
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"type": "searchText", "searchText": "<search text>"},
        "sortOptions": {"isDescending": True, "field": "CREATED_AT"},
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/spatial/v1/spatials/search",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "query": {"type": "searchText", "searchText": "<search text>"},
                "sortOptions": {"isDescending": True, "field": "CREATED_AT"},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "results": [
    {
      "rid": "<spatial rid>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<label>"
      ],
      "properties": {
        "<key>": "<property value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true,
      "daggerUuid": "<dagger uuid>",
      "typeMetadata": {
        "type": "pointCloud",
        "pointCloud": {
          "sensorModel": "<sensor model>",
          "coordinateSystem": "<coordinate system>",
          "resolutionMm": 1,
          "scanPattern": "ROTATING"
        }
      },
      "startTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "endTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "sourceHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      }
    }
  ],
  "nextPageToken": "<token>"
}
```

### Create

POST `/spatial/v1/spatials`

Creates and persists a spatial asset entity with the given metadata.

Body

`title` string required
:   ​

`daggerUuid` string (UUID) required
:   UUID of the Dagger model that backs this spatial asset. Callers must create the model in Dagger before calling create.

`typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata) required
:   ​

    **pointCloud**

    Set `type` to `"pointCloud"`.

    `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
    :   ​

        Fields of `PointCloudMetadata`

        `sensorModel` string
        :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

        `coordinateSystem` string
        :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

        `resolutionMm` number
        :   Spatial resolution of the point cloud in millimeters.

        `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
        :   The scan pattern of the lidar sensor.

            Values of `ScanPattern`

            `ROTATING`
            :   ​

            `SOLID_STATE`
            :   ​

            `FLASH`
            :   ​

            `MECHANICAL`
            :   ​

`labels` array of string
:   ​

`properties` map of `PropertyName` to string
:   ​

`markingRids` array of string (RID)
:   The markings to apply to the created spatial asset. If not provided, the asset will be visible to all users in the same workspace.

`description` string
:   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   Start of the time range covered by this spatial asset.

    Fields of `Timestamp`

    `seconds` integer (int64) required
    :   ​

    `nanos` integer (int64) required
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   End of the time range covered by this spatial asset.

`sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
:   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

    **s3**

    Set `type` to `"s3"`.

    `s3` string
    :   ​

`workspace` string (RID)
:   The workspace in which to create the spatial asset. If not provided, the asset will be created in the default workspace for the user’s organization, if the default workspace is configured.

Response

`rid` string (RID)
:   Unique resource identifier for this spatial asset.

`title` string
:   Human-readable name.

`description` string
:   Optional longer description.

`labels` array of string
:   Labels for categorization and filtering.

`properties` map of `PropertyName` to string
:   Arbitrary key-value metadata.

`createdBy` string (RID)
:   RID of the user who created this asset.

`createdAt` string (date-time)
:   When this asset was created.

`updatedAt` string (date-time)
:   When this asset was last modified.

`isArchived` boolean
:   Whether this asset has been archived.

`daggerUuid` string (UUID)
:   The UUID of the Dagger model containing this asset’s data. Supplied by the caller at create time.

`typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata)
:   Type-specific metadata (e.g. sensor metadata for point clouds). The variant of this union also serves as the type discriminator — there is no separate spatialType field.

    **pointCloud**

    Set `type` to `"pointCloud"`.

    `pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
    :   ​

        Fields of `PointCloudMetadata`

        `sensorModel` string
        :   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

        `coordinateSystem` string
        :   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

        `resolutionMm` number
        :   Spatial resolution of the point cloud in millimeters.

        `scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
        :   The scan pattern of the lidar sensor.

            Values of `ScanPattern`

            `ROTATING`
            :   ​

            `SOLID_STATE`
            :   ​

            `FLASH`
            :   ​

            `MECHANICAL`
            :   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   Start of the time range covered by this spatial asset.

    Fields of `Timestamp`

    `seconds` integer (int64)
    :   ​

    `nanos` integer (int64)
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   End of the time range covered by this spatial asset.

`sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
:   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

    **s3**

    Set `type` to `"s3"`.

    `s3` string
    :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/spatial/v1/spatials" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "<title>",
  "daggerUuid": "<dagger uuid>",
  "typeMetadata": {
    "type": "pointCloud",
    "pointCloud": {
      "sensorModel": "<sensor model>",
      "coordinateSystem": "<coordinate system>",
      "resolutionMm": 1,
      "scanPattern": "ROTATING"
    }
  }
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/spatial/v1/spatials",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "title": "<title>",
        "daggerUuid": "<dagger uuid>",
        "typeMetadata": {
            "type": "pointCloud",
            "pointCloud": {
                "sensorModel": "<sensor model>",
                "coordinateSystem": "<coordinate system>",
                "resolutionMm": 1,
                "scanPattern": "ROTATING",
            },
        },
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/spatial/v1/spatials",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "title": "<title>",
        "daggerUuid": "<dagger uuid>",
        "typeMetadata": {
            "type": "pointCloud",
            "pointCloud": {
                "sensorModel": "<sensor model>",
                "coordinateSystem": "<coordinate system>",
                "resolutionMm": 1,
                "scanPattern": "ROTATING",
            },
        },
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/spatial/v1/spatials",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "title": "<title>",
                "daggerUuid": "<dagger uuid>",
                "typeMetadata": {
                    "type": "pointCloud",
                    "pointCloud": {
                        "sensorModel": "<sensor model>",
                        "coordinateSystem": "<coordinate system>",
                        "resolutionMm": 1,
                        "scanPattern": "ROTATING",
                    },
                },
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<spatial rid>",
  "title": "<title>",
  "description": "<description>",
  "labels": [
    "<label>"
  ],
  "properties": {
    "<key>": "<property value>"
  },
  "createdBy": "<created by>",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true,
  "daggerUuid": "<dagger uuid>",
  "typeMetadata": {
    "type": "pointCloud",
    "pointCloud": {
      "sensorModel": "<sensor model>",
      "coordinateSystem": "<coordinate system>",
      "resolutionMm": 1,
      "scanPattern": "ROTATING"
    }
  },
  "startTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "endTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "sourceHandle": {
    "type": "s3",
    "s3": "<s3 path>"
  }
}
```

### Archive

PUT `/spatial/v1/spatials/{spatialRid}/archive`

Archives a spatial asset, excluding it from search. Can be unarchived.

Path parameters

`spatialRid` string (RID) required
:   ​

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X PUT "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/archive" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.put(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/archive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/archive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/archive",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

### Unarchive

PUT `/spatial/v1/spatials/{spatialRid}/unarchive`

Unarchives a previously archived spatial asset.

Path parameters

`spatialRid` string (RID) required
:   ​

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X PUT "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/unarchive" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.put(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/unarchive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/unarchive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/spatial/v1/spatials/<spatial rid>/unarchive",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

## Types

### ArchivedStatus

`NOT_ARCHIVED`
:   ​

`ARCHIVED`
:   ​

### Handle

Set `type` to the name of one of the other fields, and set only that field.

`s3` string
:   ​

### PointCloudMetadata

Metadata about the sensor that captured a point cloud.

`sensorModel` string
:   The sensor model name, e.g. “Velodyne VLP-16”, “Ouster OS1-128”.

`coordinateSystem` string
:   Coordinate reference system identifier, e.g. “EPSG:4326”, “ENU”.

`resolutionMm` number
:   Spatial resolution of the point cloud in millimeters.

`scanPattern` [`ScanPattern`](https://dev.nominal.io/api/rest/spatial-asset-service.md#scanpattern)
:   The scan pattern of the lidar sensor.

### Property

`name` string required
:   ​

`value` string required
:   ​

### ScanPattern

`ROTATING`
:   ​

`SOLID_STATE`
:   ​

`FLASH`
:   ​

`MECHANICAL`
:   ​

### SearchSpatialsQuery

Set `type` to the name of one of the other fields, and set only that field.

`searchText` string
:   ​

`label` string
:   ​

`property` [`Property`](https://dev.nominal.io/api/rest/spatial-asset-service.md#property)
:   ​

`and` array of [`SearchSpatialsQuery`](https://dev.nominal.io/api/rest/spatial-asset-service.md#searchspatialsquery)
:   ​

`or` array of [`SearchSpatialsQuery`](https://dev.nominal.io/api/rest/spatial-asset-service.md#searchspatialsquery)
:   ​

`workspace` string (RID)
:   ​

`spatialType` [`SpatialType`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtype)
:   ​

### SortField

`CREATED_AT`
:   ​

### SortOptions

`isDescending` boolean required
:   ​

`field` [`SortField`](https://dev.nominal.io/api/rest/spatial-asset-service.md#sortfield) required
:   ​

### Spatial

A spatial asset representing 3D or geospatial data (e.g. point clouds).

`rid` string (RID) required
:   Unique resource identifier for this spatial asset.

`title` string required
:   Human-readable name.

`description` string
:   Optional longer description.

`labels` array of string
:   Labels for categorization and filtering.

`properties` map of `PropertyName` to string
:   Arbitrary key-value metadata.

`createdBy` string (RID) required
:   RID of the user who created this asset.

`createdAt` string (date-time) required
:   When this asset was created.

`updatedAt` string (date-time) required
:   When this asset was last modified.

`isArchived` boolean required
:   Whether this asset has been archived.

`daggerUuid` string (UUID) required
:   The UUID of the Dagger model containing this asset’s data. Supplied by the caller at create time.

`typeMetadata` [`SpatialTypeMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#spatialtypemetadata) required
:   Type-specific metadata (e.g. sensor metadata for point clouds). The variant of this union also serves as the type discriminator — there is no separate spatialType field.

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   Start of the time range covered by this spatial asset.

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/spatial-asset-service.md#timestamp)
:   End of the time range covered by this spatial asset.

`sourceHandle` [`Handle`](https://dev.nominal.io/api/rest/spatial-asset-service.md#handle)
:   Optional reference to the original source data (e.g., S3 path) for provenance tracking.

### SpatialType

The type of spatial data stored in a spatial asset.

`POINT_CLOUD`
:   ​

### SpatialTypeMetadata

Type-specific metadata for spatial assets. Each variant holds metadata relevant to a particular spatial asset type.

Set `type` to the name of one of the other fields, and set only that field.

`pointCloud` [`PointCloudMetadata`](https://dev.nominal.io/api/rest/spatial-asset-service.md#pointcloudmetadata)
:   ​

### Timestamp

Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.

This legacy nanosecond precision timestamp type is represented by an epoch time in seconds and a nanosecond offset. The nanosecond offset is from the start of the epoch second, so must be less than 1 billion.

`seconds` integer (int64) required
:   ​

`nanos` integer (int64) required
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.