Skip to main content

Related Resources

There are two ways to work with data related to a resource:

  1. Embed it in the response with the ?include= query parameter โ€” good for reading related data alongside the parent in one request.
  2. 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.

?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.

RepresentationContents of items
Embedded compact viewrecord_id, object, display_name
Embedded expanded viewThe same compact fields plus record containing the canonical record
Related-record endpointCanonical 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"
}