Dataset relationships

List Dataset Relationships

Retrieves the relationships whose source is one of the given datasets: for example, the form a subform belongs to, or the component type dataset a component dataset implements.

A relationship points from a source dataset (dataset_id) to a related dataset (related_dataset_id). This endpoint filters on the source only; it does not return relationships in which a requested dataset is the related end.

Endpoint: GET /datasetRelationships

Authentication: Required (API Key)

Query Parameters

Parameter	Type	Required	Description
`dataset_id`	integer[]	Yes	Return the relationships out of one or more datasets (the `id` field of List Datasets). At least one, at most 200 distinct ids; a repeated id counts once.
`_page`	integer	No	Page number (positive integer, defaults to 1)
`_pageSize`	integer	No	Number of relationships per page (positive integer, defaults to 10, max 10,000; a larger value is reduced to 10,000)
`_sortBy`	string	No	Sort order. One of `+updated_at`, `-updated_at`, `+id`, `-id`; repeat the parameter for tie-breaks. Default: `+updated_at` then `+id`. Relationships that are still tied are always ordered by `id` ascending.

No other parameters are accepted: an unknown parameter (for example type) is rejected with 400.

Note: in a URL a literal + decodes to a space, so an ascending _sortBy must be percent-encoded as %2B (_sortBy=%2Bid), or simply omitted since +updated_at is the default.

Relationship Types

The type of a relationship says how the two datasets are related. A relationship always points from the child, the instance or the follow-up (dataset_id) to the parent, the template or the model (related_dataset_id).

Type	Source dataset (`dataset_id`)	Related dataset (`related_dataset_id`)
`IS_ELECTRICAL_SUBCOMPONENT_OF`	A component dataset, for example strings	The component dataset one level up in the electrical hierarchy, for example combiner boxes
`IS_MECHANICAL_SUBCOMPONENT_OF`	A component dataset	The component dataset one level up in the mechanical hierarchy
`IS_COMPONENT_OF_MODEL`	A component dataset, for example solar panels	The component model dataset that holds its models, for example solar panel models
`IMPLEMENTS`	A site-level dataset	The company-level component type or form it is based on
`IS_SUBFORM_OF`	A subform	The form it belongs to: submitting a ticket on that form also creates a ticket on the subform
`IS_TRIGGERED_BY`	A form dataset	Used between layer features; see Layer feature relationships

Because only the source can be requested, a parent cannot be used to find its children. For example, requesting a subform returns the forms it belongs to, but requesting a form does not return its subforms.

Response Format

Returns a paginated response with the following structure:

{
    "data": [
        {
            "id": "integer",
            "dataset_id": "integer",
            "related_dataset_id": "integer",
            "type": "string",
            "created_at": "timestamp",
            "updated_at": "timestamp"
        }
    ],
    "pagination": {
        "rowCount": "integer",
        "pageCount": "integer",
        "page": "integer",
        "pageSize": "integer"
    }
}

Response Fields

id: Integer ID of the relationship
dataset_id: Integer ID of the source dataset, one of the requested ids
related_dataset_id: Integer ID of the dataset the relationship points to
type: One of the relationship types listed above
created_at: ISO 8601 timestamp of when the relationship was created
updated_at: ISO 8601 timestamp of when the relationship was last changed
pagination: The standard pagination object. rowCount counts only the relationships you are allowed to see.

Ordering: by default relationships are returned by updated_at ascending, then by id ascending for relationships that share a timestamp. If a relationship is created, changed or deleted while you page through the results, rows can shift between pages, so a page walk may skip a row or return it twice.

Permissions

A relationship is returned only when your API key can read both its source and its related dataset. A relationship whose related dataset you cannot read is left out of the response and out of rowCount, even when you can read its source.

A requested dataset_id that does not exist, or that your API key cannot read, is dropped silently: it yields no rows and never causes a 403 or 404.

Example Requests

List the relationships out of a single dataset:

curl -X GET "https://api.sitemark.com/datasetRelationships?dataset_id=123" \
  -H "Authorization: ApiKey your-api-key-here"

List the relationships out of several datasets (with brackets):

curl -X GET "https://api.sitemark.com/datasetRelationships?dataset_id[]=123&dataset_id[]=456" \
  -H "Authorization: ApiKey your-api-key-here"

Most recently changed first, second page:

curl -X GET "https://api.sitemark.com/datasetRelationships?dataset_id=123&_sortBy=-updated_at&_page=2&_pageSize=100" \
  -H "Authorization: ApiKey your-api-key-here"

Example Response

Subform dataset 123 belongs to forms 456 and 789:

{
    "data": [
        {
            "id": 501,
            "dataset_id": 123,
            "related_dataset_id": 456,
            "type": "IS_SUBFORM_OF",
            "created_at": "2026-01-15T09:12:44.000Z",
            "updated_at": "2026-01-15T09:12:44.000Z"
        },
        {
            "id": 502,
            "dataset_id": 123,
            "related_dataset_id": 789,
            "type": "IS_SUBFORM_OF",
            "created_at": "2026-01-16T14:03:10.000Z",
            "updated_at": "2026-02-02T08:30:00.000Z"
        }
    ],
    "pagination": {
        "rowCount": 2,
        "pageCount": 1,
        "page": 1,
        "pageSize": 10
    }
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
400	Bad Request - Missing `dataset_id`, more than 200 distinct ids, an id that is not an integer, a `_sortBy` outside the 4 values, or an unsupported parameter
429	Too Many Requests - A rate limit was exceeded
500	Internal Server Error