Related Resources
There are two ways to work with data related to a resource:
- Embed it in the response with the
?include=query parameter โ good for reading related data alongside the parent in one request. - Access it under a nested URL โ good for operating on the relationship or paging through a large related collection.
Tourfold does not use a JSON:API-style relationships / included envelope. Included data is
embedded inline in the resource it belongs to.
Embedding related data with ?include=โ
?include= is opt-in: related data is only present when you ask for it. Repeat the parameter for
each named embeddable resource; do not send a comma-separated list:
GET /api/v2/objects/equipment/records?include=manufacturer&include=maintenance_requests
Which names are valid is defined per endpoint and documented in the
OpenAPI specification โ there is no universal include catalog. It
is available on selected read endpoints, not all of them. An unknown or non-expandable name returns
a field-level 422 pointing to #/include.
Example: device current stateโ
Device lists accept search=MOB-18, search=GPS-18, or search=TRK-18 to find the exact
displayed device identifier for its kind. The prefix is case-insensitive; other search terms match
the model, identity, phone number, or description.
GET /api/v2/devices/{device_id} and GET /api/v2/devices accept ?include=current_state. The
materialized state is embedded as a current_state field on the device, present only when
requested:
curl "https://api.tourfold.com/api/v2/devices/a1b2c3d4-e5f6-4a1b-8c9d-123456789abc?include=current_state" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"id": "a1b2c3d4-e5f6-4a1b-8c9d-123456789abc",
"kind": "TOURFOLD_APP",
"device_model": "iPhone 15",
"provisioning_state": "PROVISIONED",
"lock_version": 3,
"current_state": {
"last_received_at": "2024-01-15T10:29:00Z",
"location": { "latitude": 48.2038, "longitude": 16.3698 }
}
}
Without ?include=current_state, the current_state field is simply absent.
Example: object relationshipsโ
Object records keep workspace-defined attributes under data. Read Alpine's RTU-17 record
using its object slug (or object UUID) and record ID:
curl "https://api.tourfold.com/api/v2/objects/equipment/records/6f3d2a10-0000-4000-8000-000000000101" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"id": "6f3d2a10-0000-4000-8000-000000000101",
"display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
"created_at": "2026-03-01T08:00:00Z",
"updated_at": "2026-03-01T08:00:00Z",
"lock_version": 0,
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": false,
"maintenance_requests": {
"items": [
{
"record_id": "7a4e2b10-0000-4000-8000-000000000201",
"object": "maintenance_request",
"display_name": "Temperature too high on third floor"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
?include=maintenance_requests expands that named relationship inline. Every compact pointer gains a
record property containing the same canonical record envelope returned by a direct record read.
Unknown include names return 422; omitted relationships still carry their compact
{record_id, object, display_name} pointers.
Expansion is one level. Relationships inside the expanded record remain compact references; the
server does not recursively follow them or expand cycles implicitly. Request each relationship on
the resource where it belongs, or use GraphQL for a deliberately nested selection.
To-many relationships contain at most 50 compact views under items. Their nested page gives
the full related count. When page.total_elements exceeds items.length, use the related endpoint
to load the remaining records. Empty relationships use items: [] and zero totals.
To page RTU-17's related maintenance requests independently, use the relationship attribute slug:
curl "https://api.tourfold.com/api/v2/objects/equipment/records/6f3d2a10-0000-4000-8000-000000000101/related/maintenance_requests?page=0&size=20" \
-H "Authorization: Bearer YOUR_TOKEN"
The response uses {items, page} with typed {kind, definition_id, record} items containing the
target owner's full canonical response. See the relationship response contract.
Vehicle targets currently support paginated GET only. For Object targets, use
POST โฆ/records/{record_id}/related/{attribute_ref}/query to filter and sort within that linked
collection, POST /api/v2/objects/{object_ref}/records/query to query the top-level collection, or the
read-only GraphQL API to traverse several relationships in one read.
Defining an object relationshipโ
A relationship attribute has one fixed target. Use the singular config.target field with an object
slug or UUID; there is no polymorphic allowed_object or allowed_objects field:
{
"slug": "manufacturer",
"type": "relationship",
"name": { "en": "Manufacturer" },
"config": {
"target": "manufacturer",
"is_multiselect": false,
"reverse": {
"slug": "assets",
"name": { "en": "Assets" },
"is_multiselect": true
}
}
}
The object that declares the relationship owns its schema. Optional reverse materializes a second
attribute on the target object with is_system_managed: true and config.target pointing back to the
owner. The owning attribute is the only write surface for record links; the managed reverse cannot be written,
renamed, updated, or deleted directly. Its slug must be unused on the target object: it cannot shadow a target-owned
attribute, another relationship field, or another reverse declared in the same request. A collision returns
422 with a field error pointing to the reverse slug.
PUT /definitions/objects/{definition_ref} replaces the attributes owned by that object. Omitting an owned relationship
on its A side deletes the relationship and its reverse. Omitting the managed reverse from a B-side PUT
preserves it; sending or directly mutating it returns 422 with the field error type
relationship-reverse-managed.
Nested resource URLsโ
include changes the representation of the current resource; it is not itself a sub-resource.
Related collections are addressable through their own nested URLs. Real examples:
# Maintenance requests related to one equipment record
GET /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests
POST /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests/query
# A user's skills (whole-set; see Creating & Updating Resources for PUT semantics)
GET /api/v2/users/{user_id}/skills
PUT /api/v2/users/{user_id}/skills
# A user's tags
GET /api/v2/users/{user_id}/tags
Collection shapes and pagination capabilities are declared per operation. Paginated collections
follow the standard items + page envelope; the related-record endpoint returns the
same envelope for its complete related set. See
Pagination, Sorting & Filtering.
Embedded relationship pagesโ
Keep the configured relationship name, such as service_sites, and use {items, page} for its
collection. A compact reference is an item model: a view containing identity and display fields.
The item schema describes its contents; the envelope stays the same when more fields are included.
| Representation | Contents of items |
|---|---|
| Embedded compact view | record_id, object, display_name |
| Embedded expanded view | The same compact fields plus record containing the canonical record |
| Related-record endpoint | Canonical related records inside the documented {kind, definition_id, record} wrappers |
For example, the compact representation is:
{
"data": {
"service_sites": {
"items": [
{
"record_id": "6e606af6-71d5-4751-bdee-acc7c452f559",
"object": "service_sites",
"display_name": "Vienna warehouse"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
An empty collection uses items: []. Do not introduce refs, rename the relationship to
service_site_refs or add a discriminator just to mark a compact view. Definitions, reads,
writes, filters and include keep using the configured attribute slug. To-one relationships
return one compact reference object or explicit null when unset, without a page wrapper.
Unreadable relationships are omitted; null therefore denotes a readable but unlinked field.
Use the standard page fields.
size is the page capacity, number is zero-based, and totals describe the complete related set
readable by the caller. An empty set has total_elements: 0 and total_pages: 0. Each relationship
has its own page, independent of the parent record-list page. Counts come from the complete set,
not the preview length. Nested page replaces the former sibling relationship_page_info.
include=service_sites remains additive where supported: each entry under items retains its
compact fields and gains a record with the complete canonical response. The compact item is
therefore a subset of the expanded item. Expansion stays one level. Existing related-record
endpoints already return {items, page} with typed {kind, definition_id, record} entries;
those wrappers remain part of their contract.
Write a single UUID/reference for to-one and an array for to-many. Clear optional to-one fields
with null and to-many fields with []; omission preserves either field on PATCH. Existing to-one
array inputs remain accepted for compatibility, with at most one target. The read envelope and page metadata are not write inputs. Clients must not save a
truncated preview as the complete link set when editing another field.
This follows the general item representation convention:
items can contain documented summary models, compact views or complete records. The migration
here concerns custom relationship attributes; native aggregate arrays such as Task
linked_records do not automatically become paginated collections.
When to embed vs. use a nested URLโ
Use ?include= when:
- You need a bit of related data for display alongside the parent.
- You want to avoid a second round-trip.
Use the nested URL when:
- You need to page through a large related collection.
- You want to operate on the relationship (replace a user's skills, page related object records).
Keep ?include= lists minimal โ each included resource adds work and response size.
Error handlingโ
Errors are RFC 9457 problem documents (see Errors):
{
"type": "https://problems.tourfold.com/not-found",
"title": "Resource not found",
"detail": "No record with id 'a1b2c3d4-e5f6-4a1b-8c9d-123456789abc' exists"
}