---
title: "Add Symbol To Watchlist"
method: POST
path: "/api/watchlists/{watchlist_id}/symbols"
tags: ["watchlists"]
---

# Add Symbol To Watchlist

`POST /api/watchlists/{watchlist_id}/symbols`

## Request

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

Add a symbol to an existing watchlist.

Appends a single ticker symbol to the watchlist. Returns the updated
watchlist. Raises 404 if the watchlist does not exist.

**curl example**:
```bash
curl -X POST https://api.halalterminal.com/api/watchlists/wl_abc123/symbols \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_abc123def456" \
  -d '{"symbol": "AMZN"}'
```

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

resp = requests.post(
    "https://api.halalterminal.com/api/watchlists/wl_abc123/symbols",
    headers={"X-API-Key": "sk_live_abc123def456"},
    json={"symbol": "AMZN"},
)
updated = resp.json()
```

## Path parameters

- `watchlist_id` string, required: Watchlist ID.

## Request body

- WatchlistSymbolRequest: Request body for adding a single symbol to an existing watchlist.
  - `symbol` string, required: Stock ticker symbol to add (e.g. AAPL)

## Response `200`

The updated watchlist with the new symbol added

- 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
- `404`: Watchlist not found
- `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)