Universes

A Universe is a named membership of assets plus the dimension mappings that define how those assets are grouped across 5 dimensions: Region, Sector, Industry, Type, and Country. Each universe can define custom mappings for any dimension; undefined dimensions fall back to the macro universe.

Universe path segments and key scopes share one vocabulary — the universe slugs (e.g. macro, public-50, global-trends-200). Requesting a universe outside your key’s scope returns 403; see Authentication.

Which universes your key can reach depends on your subscription, and macro is not guaranteed — a key scoped to a single universe is a normal configuration. Examples in these pages use macro because it defines all five dimensions over the whole active screen, which makes it the clearest one to learn from. Call GET /api/universes to see yours, and substitute accordingly.

List Universes

Returns the universes your key can reach, with their membership size, dimension coverage, and config summaries. Universes outside your key’s scope are omitted rather than rejected — the list is filtered, not 403’d.

curl https://api.bytetree.io/api/universes

Query Parameters

The roster is small enough that the defaults return everything in one call; the parameters exist for envelope consistency with the rest of the API.

Response

Each universe object:

The three rank* fields describe a ranked screen, so they are absent entirely on any universe whose source is not rank — absent rather than present-and-null. Read them only after checking source.

{
  "count": 3,
  "total": 3,
  "limit": 500,
  "offset": 0,
  "data": [
    {
      "universe": "macro",
      "label": "Macro",
      "source": "all",
      "memberCount": 3062,
      "dimensions": ["region", "sector", "industry", "type", "country"],
      "fallbacks": [],
      "configs": [
        { "slug": "macro/region", "label": "Region", "category": "region", "type": "direct", "sourceField": "region", "enabled": true }
      ]
    },
    {
      "universe": "public-50",
      "label": "Public 50",
      "source": "rank",
      "memberCount": 50,
      "rankMetric": "marketCapUsd",
      "rankLimit": 50,
      "rankDirection": "desc",
      "dimensions": [],
      "fallbacks": ["region", "sector", "industry", "type", "country"],
      "configs": []
    },
    {
      "universe": "global-trends-200",
      "label": "Global Trends 200",
      "source": "rank",
      "memberCount": 200,
      "rankMetric": "marketCapUsd",
      "rankLimit": 200,
      "rankDirection": "desc",
      "dimensions": ["region", "sector", "industry"],
      "fallbacks": ["type", "country"],
      "configs": [
        { "slug": "global-trends-200/region", "label": "GT Region", "category": "region", "type": "mapped", "sourceField": "country", "enabled": true }
      ]
    }
  ]
}

Membership

source names how a universe’s membership is determined. Across the universes a customer key can reach, two values occur:

• all — the whole active screen: every active asset. macro is the only universe of this kind, and its memberCount is the size of the active screen.
• rank — a top-N ranked screen, recomputed as ranks move, not a hand-picked list. public-50 is the top 50 stocks by market cap and global-trends-200 the top 200, so memberCount tracks rankLimit.

Treat source as a string you switch on, not a closed two-value enum — branch on the values you know and fall through gracefully on anything else.

Membership and dimension mappings are independent. A ranked universe can carry bespoke mappings (global-trends-200 customises region, sector and industry), or none at all.

Empty dimensions on a ranked universe is expected

public-50 currently returns "dimensions": [] and "configs": [], with all five dimensions listed under fallbacks. This is intentional, not missing data. A universe becomes visible in the registry as soon as its membership is defined; bespoke dimension mappings and computed group metrics follow as separate steps.

Two consequences worth knowing before you build against it:

• Config lookups resolve. /api/universes/public-50/region/config returns macro’s region config with "fallback": true, so you can resolve group labels for a universe that defines none of its own.
• Group-metric coverage arrives separately. Registry visibility runs ahead of metric computation. GET /api/universes/public-50/region currently returns {"count": 0, "dimension": "public-50/region", "data": []} — the universe resolves, the request is valid, nothing has been computed for that dimension yet. An empty result here is not a rejection: a universe outside your key’s scope returns 403 instead.

Per-universe mappings and metric coverage for public-50 are on the roadmap. Treat an empty dimensions array as “inherits everything”, never as “unavailable”.

Get Dimension Config

Returns the GroupingConfig for a specific dimension within a universe. If the universe doesn’t define that dimension, automatically falls back to the macro universe’s config.

# Direct config
curl https://api.bytetree.io/api/universes/global-trends-200/region/config

# Fallback to macro (Global Trends doesn't define type)
curl https://api.bytetree.io/api/universes/global-trends-200/type/config

Response includes "fallback": true when the config comes from the macro universe.

config is a reserved value in the group position of the path — /api/universes/:universe/:category/config resolves a config, while any other value in that position is read as a group label and returns that group’s time series. A group genuinely named config is therefore unreachable; none exists in the current dimension vocabulary.

This path shares its route with the group time-series lookup, so from, to and fields are accepted here but have no effect — a config is not a time series. …/region/config?from=2020-01-01 returns the same config as …/region/config.

Config Object Fields

Resolution Types

Direct (type: "direct") — The asset’s field value is used as the group name directly.

Mapped (type: "mapped") — The asset’s field value is looked up in the mapping object. For example, sourceField: "country" with {"US": "Americas", "GB": "Europe"} maps country codes to broader regions.