---
title: "Add Watchlist"
method: POST
path: "/api/watchlist"
tags: ["Watchlist"]
---

# Add Watchlist

`POST /api/watchlist`

## Request

- Base URL: `https://api.kolens.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kolens.ai/api/watchlist`
- Auth: HTTP bearer

Idempotent: re-adding an existing (user, username, platform) returns the existing row.

``platform`` defaults to ``"tiktok"`` so legacy callers (web Star
button, plugin) keep working unchanged. The same handle on a
different platform is a separate row — the unique index is
(user_id, username, platform).

## Headers

- `x-kolens-user-id` string, nullable
- `x-kolens-workspace-id` string, nullable
- `x-kolens-locale` string, nullable

## Request body

- WatchlistAdd
  - `username` string, required
  - `platform` string

## Response `201`

Successful Response

- WatchlistEntryOut
  - `id` string, required
  - `user_id` string, required
  - `username` string, required
  - `platform` string
  - `added_at` string, required
  - `last_refreshed_at` string, nullable
  - `next_refresh_at` string, nullable
  - `is_paused` boolean, required
  - `audience_auto_refresh` boolean
  - `audience_refresh_interval_days` integer
  - `audience_sample_size` integer
  - `audience_last_refreshed_at` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)