# 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 60/min · Pro 2,000/min · Scale 10,000/min.
- **Capacity.** Hobby 5 · Pro 25 · Scale 100 · Enterprise unlimited.

## 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.
- **400** — `tickers_outside_plan_scope`, `unknown_tickers`, or other validation errors.
- **403** — `resource_limit_reached` when over the plan max.
- **409** — `slug_taken` when `id` collides with an existing universe.

## 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/api/endpoints/universes/create