Cross-Parent Reads

Read a strict-reference collection across its parents. These are additional, opt-in, read-only addresses for a collection you have already connected — they drop one or more ancestor keys from the URL so a single request can return resources belonging to more than one parent.

Why they exist

A strict_reference collection is normally addressed with every ancestor's key in the path, because each resource is owned by one parent:

GET https://{environment_key}.fxns.io/realty/accounts/{account_key}/listings/{listing_key}/photos

That keeps one parent's resources apart from another's, which is usually what you want. But some reads are naturally across parents — a portal's front page lists all listings, not the listings of one agency. A cross-parent read gives you an address for exactly that, without loosening the scoped route or changing how anything is written.

They are strictly additive. The scoped address above is unchanged and always present; a cross-parent address is a second way in that you turn on per collection.

The two forms

For a collection with L key-bearing ancestors, the levels are numbered j = 0 … L-1. Each level keeps the root-most j ancestor keys and drops the rest.

Name
Fully-flat (unscoped)
Type
j = 0
Description
Every ancestor key dropped. One request returns every resource in the collection, across all parents.
GET https://{environment_key}.fxns.io/realty/accounts/listings/photos
Returns every photo in the collection, regardless of which listing or account owns it.
Name
Partially-flat
Type
j ≥ 1
Description
The root-most j keys kept, the rest dropped. Returns every resource under one higher ancestor, across the parents in between.
GET https://{environment_key}.fxns.io/realty/accounts/{account_key}/listings/photos
Keeps the account key, drops the listing key: one request returns every photo belonging to one account, across all of that account's listings — not across all accounts.

Only "unscoped" (fully-flat, j = 0) removes the owner boundary entirely. A partially-flat address is still scoped — just to a higher ancestor than the direct parent.

What you can call on them

Cross-parent addresses are read-only. The collection's read methods apply exactly as they do on the scoped route:

List Resources — GET the address.
Search — POST .../_search at the address.
Get Resource — GET .../{resource_key} at a partially-flat address (j ≥ 1).
Schema Introspection — GET .../_schema.

There is no create, update, or delete on a cross-parent address. A flat path carries no single owner to bind a write to, so writes stay on the scoped route only. Response bodies, pagination cursors, localization, and population behave exactly as on the scoped endpoint — the only difference is which resources are in scope.

Public APIs: read this before enabling

On a public Flux API (cors_origins set, or anonymous reads open), a fully-flat (j = 0) address is an anonymous, cross-tenant read of the entire collection — anyone who knows the address can read every resource in it, with no key. A partially-flat address is anonymous given one ancestor key. This is intended for genuinely public listings, but it is a deliberate exposure: enable it only where every resource in the collection is meant to be world-readable.

On a key-authenticated API the read still requires a key whose role grants the collection's read methods — the address changes the scope, never the permission check.

Enabling

Cross-parent reads are off by default and configured per collection, per API.

Dashboard — open the collection under your Flux API and use Add a cross-parent address. Each publishable level is listed by its exact address; pick any combination. Enabling a wider level (one that drops more keys) asks for confirmation first.
Management API — set unscoped_levels (and the matching unscoped_ancestors chain the connection reports) on the collection connection. The connection object also reports flat_routes, describing every publishable level and whether it is currently enabled. The dashboard is the easier surface for this; it reads and echoes the chain for you.

A change republishes the API's router; the new address becomes reachable once that build lands (usually seconds). Router Introspection lists the cross-parent addresses that are actually being served.

Turning one off

Remove the address in the dashboard (the ✕ on the enabled row), or clear it via the Management API. Withdrawing an address never needs confirmation — it only ever reduces what is exposed — and it takes effect on the next router build. There is no data change: the resources are untouched; only the extra address stops resolving.