---
title: "Create Watchlist"
method: POST
path: "/api/watchlists"
tags: ["watchlists"]
---

# Create Watchlist

`POST /api/watchlists`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/watchlists`
- Auth: API key in header `X-API-Key`

Create a new watchlist.

Creates a named watchlist with an optional initial set of symbols.
Returns the full watchlist object including its generated ID.

**curl example**:
```bash
curl -X POST https://api.halalterminal.com/api/watchlists \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_abc123def456" \
  -d '{"name": "Halal Tech", "symbols": ["AAPL", "MSFT", "GOOGL"]}'
```

**Python example**:
```python
import requests

resp = requests.post(
    "https://api.halalterminal.com/api/watchlists",
    headers={"X-API-Key": "sk_live_abc123def456"},
    json={"name": "Halal Tech", "symbols": ["AAPL", "MSFT", "GOOGL"]},
)
watchlist = resp.json()
```

## Request body

- WatchlistCreateRequest: Request body for creating a new watchlist.
  - `name` string, required: Display name for the watchlist
  - `symbols` string[], nullable: Initial list of stock ticker symbols to include

## Response `200`

The newly created watchlist

- WatchlistResponse: Representation of a watchlist with its symbols and metadata.
  - `id` string, required: Unique watchlist identifier
  - `name` string, required: Display name of the watchlist
  - `symbols` string[], required: Ticker symbols in the watchlist
  - `count` integer, required: Number of symbols currently in the watchlist
  - `created_at` string, required: ISO-8601 timestamp when the watchlist was created
  - `updated_at` string, required: ISO-8601 timestamp of the last modification

## Other responses

- `401`: Missing or invalid API key
- `422`: Validation Error
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)