Universes

A Universe is a named collection of dimension mappings that define how assets are grouped across 4 dimensions: Region, Sector, Industry, and Type. 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, global-trends-200). Requesting a universe outside your key’s scope returns 403; see Authentication.

List Universes

Returns all available universes with their dimension coverage and config summaries.

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

Response

Field	Type	Description
`count`	`number`	Number of universes
`data`	`array`	Array of universe objects

Each universe object:

Field	Type	Description
`universe`	`string`	Universe slug (e.g. `macro`, `global-trends-200`)
`dimensions`	`string[]`	Dimensions this universe explicitly defines (e.g. `["region"]`)
`fallbacks`	`string[]`	Dimensions inherited from `macro` (e.g. `["sector", "industry", "type"]`)
`configs`	`array`	Summary of each config: slug, label, category, type, sourceField, enabled

{
  "count": 2,
  "data": [
    {
      "universe": "macro",
      "dimensions": ["region", "sector", "industry", "type"],
      "fallbacks": [],
      "configs": [
        { "slug": "macro/region", "label": "Region", "category": "region", "type": "direct", "sourceField": "region", "enabled": true }
      ]
    },
    {
      "universe": "global-trends-200",
      "dimensions": ["region", "sector", "industry"],
      "fallbacks": ["type"],
      "configs": [
        { "slug": "global-trends-200/region", "label": "GT Region", "category": "region", "type": "mapped", "sourceField": "country", "enabled": true }
      ]
    }
  ]
}

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 Object Fields

Field	Type	Description
`slug`	`string`	Unique identifier: `universe/category` (e.g. `macro/region`, `global-trends-200/region`)
`label`	`string`	Display name
`universe`	`string`	Universe slug
`category`	`string`	Dimension: `region`, `sector`, `industry`, `type`, or `country`
`type`	`string`	Resolution type: `direct` or `mapped`
`sourceField`	`string`	Asset field used as input (e.g. `region`, `country`, `sector`, `industry`, `type`)
`mapping`	`object \| null`	For `mapped` type: lookup table from source value to group label. `null` for `direct`.
`unmappedStrategy`	`string`	`exclude` (skip unmapped values) or `fallback` (assign to the configured fallback group)
`fallbackGroup`	`string \| null`	Group label for unmapped values when strategy is `fallback`
`enabled`	`boolean`	Whether this dimension is actively computed

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.