> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testnet.dev.adipredictstreet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events overview

> Polymarket-style event grouping with football metadata, tags, and filters.

PredictStreet groups one or more markets under an **Event**. A single
match (Real Madrid vs Manchester City) typically maps to one event with
one binary market. A tournament (UEFA Champions League winner) maps to
one event with many per-team markets shown as a Polymarket-style
accordion via `groupItemTitle`.

Every public market response includes the parent event slug; every
event response carries its full markets array. Most clients query
`GET /api/events` for the home grid and fall back to
`GET /api/markets/{symbol}` for the trading detail page.

## Event shape

```json theme={null}
{
  "id": "e005f649-2d64-4e37-8513-5463c26f28c6",
  "slug": "m1v1-rma-mci-959311",
  "title": "Real Madrid (ESP) vs Manchester City (ENG) — UCL R16",
  "group": null,
  "stage": "r16",
  "teamA": "ESP",
  "teamB": "ENG",
  "tags": [
    { "slug": "soccer", "name": "Soccer" },
    { "slug": "champions-league", "name": "UEFA Champions League" },
    { "slug": "knockout", "name": "Knockout" },
    { "slug": "match", "name": "Single Match" }
  ],
  "eventStartTime": "2026-04-30T15:48:31Z",
  "createdAt": "2026-04-23T15:48:31Z",
  "updatedAt": "2026-04-23T15:50:37Z",
  "markets": [ { "...": "MarketSummary" } ]
}
```

### Football metadata fields

| Field             | When populated                                                                                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group`           | Tournament group letter (`A`..`L`). Set on group-stage events only.                                                                                                                      |
| `stage`           | `group` / `r32` / `r16` / `quarter_finals` / `semi_finals` / `third_place` / `final`. Null for non-fixture events.                                                                       |
| `teamA` / `teamB` | FIFA 3-letter country codes. Both populated for 1-vs-1 fixtures; only `teamA` for tournament-winner markets in focus on a single team; both null for picker-style multi-outcome markets. |
| `tags`            | Curated taxonomy from `GET /api/tags`. Use the slug as `?tag=<slug>` to filter.                                                                                                          |
| `eventStartTime`  | Real-world fixture kickoff. Separate from `createdAt`.                                                                                                                                   |

### Per-market fields driven by the event grouping

| Field on `MarketSummary` | Meaning                                                                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `groupItemTitle`         | Per-market label inside the event accordion (e.g. `"Real Madrid"`, `"Liverpool"`, `"Draw"`). Equal to `title` for single-market events. |
| `initialOutcomePrices`   | Per-outcome seed price aligned to `outcomeLabels`. Equivalent to Polymarket's `outcomePrices`.                                          |

## Filtering

```http theme={null}
GET /api/events?stage=r16&tag=champions-league
GET /api/events?team=BRA
GET /api/events?group=A&from=2026-06-11T00:00:00Z&to=2026-06-26T00:00:00Z
GET /api/events?sort=trending
```

| Query         | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stage`       | Exact match against the `EventStage` enum.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `group`       | Group letter; case-sensitive.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `team`        | FIFA 3-letter code matched against teamA OR teamB.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `tag`         | Single tag slug, exact match. Combine with other filters via repeated requests; the API does not support multi-tag in a single call.                                                                                                                                                                                                                                                                                                                                        |
| `from` / `to` | Inclusive bounds on `eventStartTime`.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sort`        | `trending` (24h volume DESC) / `ending_soon` (non-past `closesAt` ASC) / `starting_soon` (future market `kickoff` ASC) / `live` (kickoff passed and a market is still OPEN; most-recently-started DESC). Default (no `sort`): earliest public-market `kickoff` ASC, then `title` ASC, then event `id` ASC — **not** `createdAt`. `starting_soon` / `live` use per-market `kickoff` as the source of truth; `eventStartTime` is a fallback used only when `kickoff` is NULL. |

All filters AND together. Events with no public-status (OPEN /
PRE\_MARKET / PAUSED / PROPOSED) market are excluded from the response
entirely — the public surface never returns "empty" events.

## Tags

The tag taxonomy is admin-curated rather than free-form. Use
`GET /api/tags` for the full active list and the `slug` as the value
for `?tag=`.

```http theme={null}
GET /api/tags
```

```json theme={null}
{
  "tags": [
    { "slug": "soccer",        "name": "Soccer",                  "sortOrder": 1,  "isFeatured": true },
    { "slug": "world-cup-2026","name": "World Cup 2026",           "sortOrder": 5,  "isFeatured": true },
    { "slug": "premier-league","name": "Premier League",           "sortOrder": 10, "isFeatured": false },
    { "slug": "champions-league","name": "UEFA Champions League",  "sortOrder": 11, "isFeatured": false }
  ]
}
```

`isFeatured` tags are surfaced in the primary navigation strip;
non-featured tags remain selectable through filter UI but are not
pinned.