# POST /v2/universes

**Create a universe**

Create a named ticker list owned by the calling account. Body: `{ id?, name, description?, tickers }`. If `id` is omitted, a slug is generated.

## Plan access

- **Plan access.** Included on every plan.
- **Rate limit.** Hobby 600/min · Pro 2,000/min · Scale 10,000/min.
- **Capacity.** Unlimited on every paid plan.

## Body parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `id` | body | string | no | Optional slug. Lowercase letters, digits, underscore. Must be unique within your account. Example: `my_watchlist`. |
| `name` | body | string | yes | Human-readable label. |
| `description` | body | string | no | Free-form notes. |
| `tickers` | body | string[] | yes | Ticker symbols. Validated against your plan scope + the active universe. |

## Status codes

- **201** — Universe created. Returns the full universe doc.
- **400** — `bad_request` for malformed tickers or oversized universe; `unknown_tickers` (with a `disallowed` array) when symbols aren't in our universe.
- **403** — `universes_tier_required` if the plan lacks universes, or `resource_limit_reached` when over the plan cap. (Every paid plan ships unlimited universes — this only fires on internal/Enterprise caps.)
- **409** — `slug_taken` when `id` collides with one of your existing universes.

## Sample response

```json
{
  "as_of": "2026-05-14T11:41:01.000Z",
  "id": "my_watchlist",
  "name": "My Watchlist",
  "description": null,
  "tickers": ["AAPL", "NVDA", "TSLA"],
  "size": 3,
  "system": false,
  "created_at": 1778720416,
  "updated_at": 1778720416
}
```

## Examples

### Create

Request:

```shell
curl -X POST "https://api.tickerbot.io/v2/universes" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"my_watchlist","name":"My Watchlist","tickers":["AAPL","NVDA","TSLA"]}'
```

Response (`200`):

```json
{
  "as_of": "2026-05-14T11:41:01.000Z",
  "id": "my_watchlist",
  "name": "My Watchlist",
  "description": null,
  "tickers": ["AAPL", "NVDA", "TSLA"],
  "size": 3,
  "system": false,
  "created_at": 1778720416,
  "updated_at": 1778720416
}
```

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/universes/create