# Universes

A universe is a named ticker list you can point any query at.

- **Create a universe** — `POST /v2/universes`
- **Get one universe** — `GET /v2/universes/{id}`
- **Get all universes** — `GET /v2/universes`
- **Update a universe** — `PATCH /v2/universes/{id}`
- **Delete a universe** — `DELETE /v2/universes/{id}`

## Where a slug can be used

One slug, the same meaning on every read and on webhook triggers.

| Surface | How |
| --- | --- |
| Scan (`/v2/scan`) | `?universe=` restricts the scan to that universe's members. |
| Signal matches (`/v2/signals/{signal}`) | `?universe=` restricts the match set. |
| Events (`/v2/events`) | `?universe=` scopes the stream (mutually exclusive with `tickers`). |
| Ticker lookup (`/v2/tickers`) | `?universe=` returns full rows for every member — a bulk lookup. |
| Webhook triggers | Scope a scan / signal / event subscription with `universe` (stored as `universe_id`). |

## System universes

`top_10` and `top_100` are system-managed — read-only, rebalanced monthly, and usable as a `?universe=` slug anywhere your own are. Those two slugs are reserved: you can't create a universe that shadows them. They show up in the list alongside yours — filter with `GET /v2/universes?owner=system` (or `owner=all`); each row carries `system: true|false`.

## Limits

An account may hold up to **1,000** universes — a flat anti-abuse ceiling, identical for every account. A single universe holds up to **10,000** tickers — larger creates and updates are refused with `400`. Referencing a universe you don't own (other than the system ones) returns `404`.