Segmentation & Tags

Every flow is tagged along two independent axes so you can segment the feed
precisely:

Content tags describe what a flow is about — the narrative angle, e.g.
hot streak, rivalry, revenge game.
Metadata tags describe structural attributes of the flow — e.g. the league
(NBA), the position (point guard), or the market type.

Tags are organized into dimensions and arranged in a hierarchy of tag
types. This guide covers how to discover the tag registry and how to apply tag
IDs as filters on the flows endpoints.

Discover the tag registry

Tag dimensions

List the available tag dimensions for a flow type. Pass flow_type to scope the
dimensions to the kind of content you're filtering (fact_flows, fun_flows,
plain_flows, parlays, singles).

curl "https://api.odditt.com/v1/references/tag-dimensions?flow_type=fact_flows" \
 -H "X-API-Key: YOUR_API_KEY"

See GET /v1/references/tag-dimensions.

Search tag types

Search the tag-type registry by name. Returns paginated tag types with their IDs,
which you then pass as filters.

curl "https://api.odditt.com/v1/references/tag-types/search?search=weather&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

Optional query parameters:

Parameter	Description
`search_mode`	`starts_with` (default), `ends_with`, or `contains`
`dimension`	Restrict to a dimension (e.g. `event`, `metadata`)
`flow_type`	Restrict to a flow type (`fact_flows`, `fun_flows`, `plain_flows`, `parlays`, `singles`)
`terminal_only`	When `true`, return only leaf (terminal) tag types
`tag_level`	Restrict to a specific depth in the hierarchy

See GET /v1/references/tag-types/search.

Tag type children

Walk the hierarchy by fetching the children of a tag type. Useful for building a
drill-down tag picker.

curl "https://api.odditt.com/v1/references/tag-types/463076/children?flow_type=fact_flows" \
 -H "X-API-Key: YOUR_API_KEY"

Pass include_values=true to also return the concrete tag values under each
child. See
GET /v1/references/tag-types/{tag_type_id}/children.

Filter flows by tag

Once you have tag type IDs from the registry, apply them on
/v1/trends/mixed-flows or
/v1/trends/flows:

Field	Type	Description
`content_tag_type_ids`	number[]	Filter by what the flow is about. OR mode by default.
`content_tag_require_all`	boolean	When `true`, a flow must match all content tags (AND).
`metadata_tag_type_ids`	number[]	Filter by structural attributes. OR mode by default.
`metadata_tag_require_all`	boolean	When `true`, a flow must match all metadata tags (AND).
`include_star_sign_content`	boolean	Opt in to star-sign / horoscope-themed content (fact/plain parlay only).

curl -X POST https://api.odditt.com/v1/trends/mixed-flows \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "flow_type": "fact",
    "bet_type": "parlay",
    "sport_id": 3,
    "league_id": 75,
    "content_tag_type_ids": [15, 42],
    "content_tag_require_all": false,
    "metadata_tag_type_ids": [201, 205],
    "metadata_tag_require_all": true,
    "include_star_sign_content": true,
    "page": 1,
    "page_size": 20
  }'

In this example a flow must be about either tag 15 or 42 (content, OR), and
must carry both metadata tags 201 and 205 (AND).

📘
Tip
The tag type IDs in examples are illustrative — resolve real IDs from your tag
registry via the search and children endpoints above before filtering.

Next Steps

Filtering & Query Parameters - all shared filters
Getting Started - flows and mixed flows basics
Browse the API Reference for full schemas