Relations (Eager Loading)

Load related entities alongside the main resource using the with query parameter.

Syntax

?with=relation1,relation2

Nested Relations

Use dot notation to load nested relations:

?with=categories.translations
?with=categories.articles.translations

Self-Relations (Recursive)

For tree structures (e.g., categories with children), use the * wildcard to load all levels:

?with=children*                    # Load all descendant levels
?with=children*.translations       # Load all levels with their translations

Multiple Relations

Combine relations with commas:

?with=translations,categories.translations,vendor,images

Available Relations

Each endpoint's tag description lists its supported relations. Requesting an unsupported relation is silently ignored.

Scope-Based Filtering

The set of available relations depends on your authentication scope:

Scope	Behavior
Public	Only public-safe relations are available
Customer	Public relations + customer-specific relations
Backend	All relations available

If you request a relation that isn't allowed for your scope, it is silently stripped from the response (no error returned).

Constrain Parameter

By default, relations inherit the parent query's filters where applicable. To disable this:

?with=categories&constrain=false

Discovering Relations from the OpenAPI Spec

Each resource's OpenAPI tag includes a vendor extension x-relations that lists all available relations with their cardinality type:

Cardinality	Meaning
belongs_to	The entity holds a foreign key to the related entity (e.g., product belongs to vendor)
one_to_many	The related entity holds a foreign key back to this entity (e.g., product has many images)
many_to_many	A pivot table connects the two entities (e.g., product has many categories)

Example x-relations excerpt from a tag definition:

x-relations:
  translations:
    type: one_to_many
  categories:
    type: many_to_many
  vendor:
    type: belongs_to
  images:
    type: one_to_many

Use these vendor extensions to programmatically discover which relations are available for each resource and understand their cardinality without trial and error.