Datasets

Datasets represent collections of data in the Sitemark platform. They are the primary containers for all types of geospatial and structured data.

Datasets exist at three levels:

Company-level: Span across sites and operations (e.g. component models). These have site_id = null and operation_id = null.
Site-level: Linked to a specific site, span across operations (e.g. design files, tickets, components). These have a site_id but operation_id = null.
Operation-level: Linked to a specific operation (e.g. detection outputs, orthomosaics, point clouds). These have both a site_id and operation_id.

Each dataset has a type (how the data is stored) and a semantic_type (what the data represents). Some common combinations:

Use case	Type	Semantic type
Tickets / punch list	`geojson-layer`	`PUNCH_LIST_ITEMS`
Solar panel components	`geojson-layer`	`SOLAR_PANELS`
Solar anomaly detections	`geojson-layer`	`SOLAR_ANOMALIES`
Annotations	`geojson-layer`	`ANNOTATIONS`
Visual orthomosaic	`tile-layer`	`RGB`
Thermal orthomosaic	`tile-layer-raw`	`THERMAL`
Digital surface model	`tile-layer-raw`	`DIGITAL_SURFACE_MODEL`
3D point cloud	`3d-point-cloud`	`RGB`
Design file (PDF)	`georeferenced-pdf`	—
Design file (DXF)	`dxf`	—

List Datasets

Retrieves a paginated list of datasets.

Endpoint: GET /datasets

Authentication: Required (API Key)

Query Parameters

Parameter	Type	Required	Description
`id`	integer[]	No	Filter datasets by one or more dataset IDs.
`site_id`	(integer\|null)[]	No	Filter datasets by one or more site IDs. Supports `null` to filter for company-level datasets.
`operation_id`	(integer\|null)[]	No	Filter datasets by one or more operation IDs. Supports `null` to filter for site-level and company-level datasets.
`type`	string[]	No	Filter datasets by one or more dataset types.
`status`	string[]	No	Filter datasets by one or more statuses.
`semantic_type`	(string\|null)[] (enum)	No	Filter datasets by one or more semantic types. See Semantic Types. Supports `null` for untyped datasets.
`_page`	integer	No	Page number (positive integer, defaults to 1)
`_pageSize`	integer	No	Number of items per page (positive integer, defaults to 10, max 10,000)
`_sortBy`	string	No	Sort order. Format: `+field` or `-field`. Sortable fields: `id`, `created_at`, `updated_at`. Default: `-id`

Response Format

{
    "data": [
        {
            "id": "integer",
            "identifier": "string",
            "site_id": "integer",
            "operation_id": "integer",
            "name": "string",
            "status": "string",
            "semantic_type": "string",
            "layout_definition": {
                "items": [
                    { "type": "PROPERTY", "property_definition_id": "string (UUID)" },
                    {
                        "type": "SECTION",
                        "header": "string (optional)",
                        "items": [{ "type": "PROPERTY", "property_definition_id": "string (UUID)" }]
                    }
                ]
            }
        }
    ],
    "pagination": {
        "page": "integer",
        "pageSize": "integer",
        "rowCount": "integer",
        "pageCount": "integer"
    }
}

Response Fields

id: Integer ID of the dataset
identifier: String identifier of the dataset
site_id: Integer ID of the associated site. Null for company-level datasets.
operation_id: Integer ID of the associated operation. Null for site-level and company-level datasets.
name: Name of the dataset
status: Status of the dataset (e.g. COMPLETED, PROCESSING)
semantic_type: Semantic type classification (can be null)
layout_definition: Object describing how the dataset’s properties are laid out for display (can be null). The flat, in-order sequence of PROPERTY entries (descending into sections) defines property display order — use this instead of the deprecated display_order field on property definitions. Its items array is the ordered list of layout entries; each entry is one of:
- PROPERTY — references a property definition via property_definition_id.
- SECTION — a group with an optional header and its own nested PROPERTY items.

Example Requests

List all datasets:

curl -X GET "https://api.sitemark.com/datasets?_pageSize=25" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by site to get all ticket datasets:

curl -X GET "https://api.sitemark.com/datasets?site_id=5678&type=geojson-layer&semantic_type=PUNCH_LIST_ITEMS&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
400	Bad Request - Invalid query parameters
500	Internal Server Error