Organizations, Clusters, and Locations

Spatial data is organized as clusters with locations inside them. A cluster can be owned by a user or organization, and it can also be shared with users or organizations.

Cluster responses include display metadata for map and list UIs: color is a muted #RRGGBB background color, and useLightText tells clients whether light text should be used over that color. POST /v1/spatial/clusters and PATCH /v1/spatial/clusters/{clusterId} accept an optional color as #RGB or #RRGGBB; if a new cluster omits it, the API chooses from a generated muted color set to contrast with the owner's existing cluster colors.

Listing Across Clusters

Use the cluster list first when a client needs a picker:

GET /v1/spatial/clusters

For read-only views that span more than one cluster, use the aggregate routes:

GET /v1/spatial/locations
GET /v1/spatial/documents
GET /v1/spatial/documents/types

Omit clusterIds to include all clusters the current user can read. Provide clusterIds as repeated query values or a comma-separated list to limit the response to selected clusters:

GET /v1/spatial/locations?clusterIds=11111111-1111-1111-1111-111111111111,22222222-2222-2222-2222-222222222222
GET /v1/spatial/documents?clusterIds=11111111-1111-1111-1111-111111111111

The document aggregate route lists documents attached directly to clusters. It does not include documents attached to individual locations.

Location list and detail responses include annotationCount, so clients can show annotation badges without fetching each location's annotation list first.

POST /v1/spatial/clusters/{clusterId}/locations requires a non-empty name. Create and patch requests accept optional latitude, longitude, and altitude: latitude must be finite and between -90 and 90, longitude must be finite and between -180 and 180, and altitude must be finite when provided.

Location Annotations

Annotations belong to locations and can represent a point, line, or polygon. New clients should send geometryType with coordinates; each coordinate is [longitude, latitude] or [longitude, latitude, altitude], and altitude can be null when altitudeMode is clampToSurface. The older position field remains the anchor point and is still accepted for point annotations.

Annotation responses include workflow and display metadata: category, status, optional priority, optional hex color, optional savedView, authorUserId, optional assigneeUserId, and linked documents. Authorship is server-owned and comes from the authenticated creator. Assignees must already be able to read the cluster that contains the location.

Use documentIds on create or update to link location documents, such as uploaded inspection images, to an annotation. The link is stored by document id, not by filename or folder path. Renaming a document or moving it to another folder keeps the annotation link intact, and deleting the document removes it from the annotation response.

{
  "title": "Facade crack",
  "geometryType": "point",
  "coordinates": [[10.5, 53.5, null]],
  "documentIds": [
    "44444444-4444-4444-4444-444444444444"
  ]
}

Annotation lists can be filtered with category, status, and updatedSince. category and status can be repeated or sent as comma-separated values, for example ?category=defect,hazard&status=open&status=in_progress. updatedSince is an inclusive ISO 8601 timestamp filter against updatedAt, falling back to createdAt for records that have not been updated.