{ "swagger": "2.0", "info": { "title": "Spatial asset service", "version": "0.1507.0", "description": "Send your API key as a bearer token: `Authorization: Bearer `." }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "securityDefinitions": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your API key as a bearer token: `Authorization: Bearer `." } }, "security": [ { "ApiKey": [] } ], "paths": { "/spatial/v1/spatials/{spatialRid}": { "get": { "operationId": "SpatialService_get", "summary": "Get", "tags": [ "Spatial Asset Service" ], "description": "Returns spatial asset metadata associated with a spatial asset rid.", "parameters": [ { "name": "spatialRid", "in": "path", "type": "string", "format": "rid", "x-alias": "SpatialRid", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Spatial" }, "x-example": { "rid": "", "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>" } } } } }, "put": { "operationId": "SpatialService_updateMetadata", "summary": "Update metadata", "tags": [ "Spatial Asset Service" ], "description": "Updates the metadata for a spatial asset associated with the given rid.", "parameters": [ { "name": "spatialRid", "in": "path", "type": "string", "format": "rid", "x-alias": "SpatialRid", "required": true }, { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/UpdateSpatialMetadataRequest" }, "required": true, "x-example": { "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>" } } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Spatial" }, "x-example": { "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>" } } } } } }, "/spatial/v1/spatials/batchGet": { "post": { "operationId": "SpatialService_batchGet", "summary": "Batch get", "tags": [ "Spatial Asset Service" ], "description": "Returns spatial asset metadata for each given spatial asset rid.", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/GetSpatialsRequest" }, "required": true, "x-example": { "spatialRids": [ "<spatial rid>" ] } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/GetSpatialsResponse" }, "x-example": { "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>" } } ] } } } } }, "/spatial/v1/spatials/search": { "post": { "operationId": "SpatialService_search", "summary": "Search", "tags": [ "Spatial Asset Service" ], "description": "Returns metadata about spatial assets that match a given query.", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/SearchSpatialsRequest" }, "required": true, "x-example": { "query": { "type": "searchText", "searchText": "<search text>" }, "sortOptions": { "isDescending": true, "field": "CREATED_AT" } } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/SearchSpatialsResponse" }, "x-example": { "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>" } } } } }, "/spatial/v1/spatials": { "post": { "operationId": "SpatialService_create", "summary": "Create", "tags": [ "Spatial Asset Service" ], "description": "Creates and persists a spatial asset entity with the given metadata.", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/CreateSpatialRequest" }, "required": true, "x-example": { "title": "<title>", "daggerUuid": "<dagger uuid>", "typeMetadata": { "type": "pointCloud", "pointCloud": { "sensorModel": "<sensor model>", "coordinateSystem": "<coordinate system>", "resolutionMm": 1, "scanPattern": "ROTATING" } } } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Spatial" }, "x-example": { "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>" } } } } } }, "/spatial/v1/spatials/{spatialRid}/archive": { "put": { "operationId": "SpatialService_archive", "summary": "Archive", "tags": [ "Spatial Asset Service" ], "description": "Archives a spatial asset, excluding it from search. Can be unarchived.", "parameters": [ { "name": "spatialRid", "in": "path", "type": "string", "format": "rid", "x-alias": "SpatialRid", "required": true } ], "responses": { "204": { "description": "No content." } } } }, "/spatial/v1/spatials/{spatialRid}/unarchive": { "put": { "operationId": "SpatialService_unarchive", "summary": "Unarchive", "tags": [ "Spatial Asset Service" ], "description": "Unarchives a previously archived spatial asset.", "parameters": [ { "name": "spatialRid", "in": "path", "type": "string", "format": "rid", "x-alias": "SpatialRid", "required": true } ], "responses": { "204": { "description": "No content." } } } } }, "definitions": { "ArchivedStatus": { "type": "string", "enum": [ "NOT_ARCHIVED", "ARCHIVED" ] }, "Handle": { "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "s3": { "type": "string", "x-alias": "S3Path" } }, "required": [ "type" ], "description": "Set `type` to the name of one of the other fields, and set only that field.", "example": { "type": "s3", "s3": "string" } }, "Property": { "type": "object", "properties": { "name": { "type": "string", "x-alias": "PropertyName" }, "value": { "type": "string", "x-alias": "PropertyValue" } }, "required": [ "name", "value" ] }, "Timestamp": { "description": "Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.\n\nThis 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.", "type": "object", "properties": { "seconds": { "type": "integer", "format": "int64" }, "nanos": { "type": "integer", "format": "int64" } }, "required": [ "seconds", "nanos" ] }, "CreateSpatialRequest": { "type": "object", "properties": { "title": { "type": "string" }, "daggerUuid": { "type": "string", "format": "uuid", "description": "UUID of the Dagger model that backs this spatial asset. Callers must create the model in Dagger before calling create." }, "typeMetadata": { "$ref": "#/definitions/SpatialTypeMetadata" }, "labels": { "type": "array", "items": { "type": "string", "x-alias": "Label" }, "uniqueItems": true }, "properties": { "type": "object", "additionalProperties": { "type": "string", "x-alias": "PropertyValue" }, "x-map-key": "PropertyName" }, "markingRids": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "MarkingRid" }, "uniqueItems": true, "description": "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": { "type": "string" }, "startTimestamp": { "allOf": [ { "$ref": "#/definitions/Timestamp" } ], "description": "Start of the time range covered by this spatial asset." }, "endTimestamp": { "allOf": [ { "$ref": "#/definitions/Timestamp" } ], "description": "End of the time range covered by this spatial asset." }, "sourceHandle": { "allOf": [ { "$ref": "#/definitions/Handle" } ], "description": "Optional reference to the original source data (e.g., S3 path) for provenance tracking." }, "workspace": { "type": "string", "format": "rid", "x-alias": "WorkspaceRid", "description": "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." } }, "required": [ "title", "daggerUuid", "typeMetadata" ], "example": { "title": "<title>", "daggerUuid": "<dagger uuid>", "typeMetadata": { "type": "pointCloud", "pointCloud": { "sensorModel": "<sensor model>", "coordinateSystem": "<coordinate system>", "resolutionMm": 1, "scanPattern": "ROTATING" } } } }, "GetSpatialsRequest": { "type": "object", "properties": { "spatialRids": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "SpatialRid" }, "uniqueItems": true } }, "example": { "spatialRids": [ "<spatial rid>" ] } }, "GetSpatialsResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "$ref": "#/definitions/Spatial" }, "uniqueItems": true } } }, "PointCloudMetadata": { "description": "Metadata about the sensor that captured a point cloud.", "type": "object", "properties": { "sensorModel": { "type": "string", "description": "The sensor model name, e.g. \"Velodyne VLP-16\", \"Ouster OS1-128\"." }, "coordinateSystem": { "type": "string", "description": "Coordinate reference system identifier, e.g. \"EPSG:4326\", \"ENU\"." }, "resolutionMm": { "type": "number", "format": "double", "description": "Spatial resolution of the point cloud in millimeters." }, "scanPattern": { "allOf": [ { "$ref": "#/definitions/ScanPattern" } ], "description": "The scan pattern of the lidar sensor." } } }, "ScanPattern": { "type": "string", "enum": [ "ROTATING", "SOLID_STATE", "FLASH", "MECHANICAL" ] }, "SearchSpatialsQuery": { "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "searchText", "label", "property", "and", "or", "workspace", "spatialType" ] }, "searchText": { "type": "string" }, "label": { "type": "string", "x-alias": "Label" }, "property": { "$ref": "#/definitions/Property" }, "and": { "type": "array", "items": { "$ref": "#/definitions/SearchSpatialsQuery" }, "uniqueItems": true }, "or": { "type": "array", "items": { "$ref": "#/definitions/SearchSpatialsQuery" }, "uniqueItems": true }, "workspace": { "type": "string", "format": "rid", "x-alias": "WorkspaceRid" }, "spatialType": { "$ref": "#/definitions/SpatialType" } }, "required": [ "type" ], "description": "Set `type` to the name of one of the other fields, and set only that field.", "example": { "type": "searchText", "searchText": "string" } }, "SearchSpatialsRequest": { "type": "object", "properties": { "query": { "$ref": "#/definitions/SearchSpatialsQuery" }, "pageSize": { "type": "integer", "format": "int32", "description": "Defaults to 100. Will throw if larger than 1000." }, "token": { "type": "string", "x-alias": "Token" }, "sortOptions": { "$ref": "#/definitions/SortOptions" }, "archivedStatuses": { "type": "array", "items": { "$ref": "#/definitions/ArchivedStatus" }, "uniqueItems": true, "description": "Default search status is NOT_ARCHIVED if none are provided." } }, "required": [ "query", "sortOptions" ], "example": { "query": { "type": "searchText", "searchText": "<search text>" }, "sortOptions": { "isDescending": true, "field": "CREATED_AT" } } }, "SearchSpatialsResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/Spatial" } }, "nextPageToken": { "type": "string", "x-alias": "Token" } } }, "SortField": { "type": "string", "enum": [ "CREATED_AT" ] }, "SortOptions": { "type": "object", "properties": { "isDescending": { "type": "boolean" }, "field": { "$ref": "#/definitions/SortField" } }, "required": [ "isDescending", "field" ] }, "Spatial": { "description": "A spatial asset representing 3D or geospatial data (e.g. point clouds).", "type": "object", "properties": { "rid": { "type": "string", "format": "rid", "x-alias": "SpatialRid", "description": "Unique resource identifier for this spatial asset." }, "title": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Optional longer description." }, "labels": { "type": "array", "items": { "type": "string", "x-alias": "Label" }, "uniqueItems": true, "description": "Labels for categorization and filtering." }, "properties": { "type": "object", "additionalProperties": { "type": "string", "x-alias": "PropertyValue" }, "x-map-key": "PropertyName", "description": "Arbitrary key-value metadata." }, "createdBy": { "type": "string", "format": "rid", "description": "RID of the user who created this asset." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this asset was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this asset was last modified." }, "isArchived": { "type": "boolean", "description": "Whether this asset has been archived." }, "daggerUuid": { "type": "string", "format": "uuid", "description": "The UUID of the Dagger model containing this asset's data. Supplied by the caller at create time." }, "typeMetadata": { "allOf": [ { "$ref": "#/definitions/SpatialTypeMetadata" } ], "description": "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": { "allOf": [ { "$ref": "#/definitions/Timestamp" } ], "description": "Start of the time range covered by this spatial asset." }, "endTimestamp": { "allOf": [ { "$ref": "#/definitions/Timestamp" } ], "description": "End of the time range covered by this spatial asset." }, "sourceHandle": { "allOf": [ { "$ref": "#/definitions/Handle" } ], "description": "Optional reference to the original source data (e.g., S3 path) for provenance tracking." } }, "required": [ "rid", "title", "createdBy", "createdAt", "updatedAt", "isArchived", "daggerUuid", "typeMetadata" ] }, "SpatialType": { "description": "The type of spatial data stored in a spatial asset.", "type": "string", "enum": [ "POINT_CLOUD" ] }, "SpatialTypeMetadata": { "description": "Type-specific metadata for spatial assets. Each variant holds metadata relevant to a particular spatial asset type.\n\nSet `type` to the name of one of the other fields, and set only that field.", "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "pointCloud" ] }, "pointCloud": { "$ref": "#/definitions/PointCloudMetadata" } }, "required": [ "type" ], "example": { "type": "pointCloud", "pointCloud": { "sensorModel": "string", "coordinateSystem": "string", "resolutionMm": 1, "scanPattern": "ROTATING" } } }, "UpdateSpatialMetadataRequest": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string", "x-alias": "Label" }, "uniqueItems": true }, "properties": { "type": "object", "additionalProperties": { "type": "string", "x-alias": "PropertyValue" }, "x-map-key": "PropertyName" }, "typeMetadata": { "$ref": "#/definitions/SpatialTypeMetadata" }, "startTimestamp": { "$ref": "#/definitions/Timestamp" }, "endTimestamp": { "$ref": "#/definitions/Timestamp" }, "sourceHandle": { "$ref": "#/definitions/Handle" } }, "example": { "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>" } } } }, "tags": [ { "name": "Spatial Asset Service", "x-displayName": "Spatial asset service", "description": "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." } ] }