CopyHero
Back to CopyHero

Add Store

POST
/api/v1/watchlist/stores

Add a competitor store URL — create-or-subscribe (hidden sharing).

Authorization

HTTPBearer
headerAuthorizationBearer <token>

Request Body

application/json
  1. body

POST /watchlist/stores — add a competitor store URL to the watchlist.

The raw URL is normalized to its https origin server-side (the globally unique key). Create-or-subscribe is transparent to the caller.

url*Url

A public Shopify store URL to watch.

Response Body

Successful Response

application/json
  1. response

A watched store as seen by ONE subscriber. Store status is global; the subscription fields are the viewer's own. Deliberately carries NO precise scan timestamps (next_scan_at / precise last_scan_at) — those would leak a co-watcher's cadence (CONCEPT §9 F8.1).

id*Id
Formatuuid
url*Url
name?string|null
status*WatchedStoreStatus

Scan-health status of a watched store (a display badge only — products stay visible regardless of status). Stored as plain text (no Postgres ENUM, like RevisionActorType) so a new value is zero-DDL. pending is the pre-first-scan state; unreachable = DNS/timeout/conn error; invalid = reachable but not a public Shopify store (password page / 401/403 / not Shopify JSON).

Value in"pending""active""unreachable""invalid"
status_detail?string|null
product_count*Product Count
initial_crawl_completed*Initial Crawl Completed
listings_last_7_days*Listings Last 7 Days
Range0 <= value
listings_last_30_days*Listings Last 30 Days
Range0 <= value
listing_activity_12m*array<>
traffic_country?string|null
search_traffic_12m?array<integer|null>
screenshot_url?string|null
tracking_pixels?|null
paused*Paused
scan_interval_minutes?integer|null
subscribed_at*Subscribed At
Formatdate-time
tags?array<string>
Example Request
curl -X POST 'https://app.copyhero.app/api/v1/watchlist/stores' \  -H 'Content-Type: application/json' \  -d '{  "url": "string"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "string",  "name": "string",  "status": "pending",  "status_detail": "string",  "product_count": 0,  "initial_crawl_completed": true,  "listings_last_7_days": 0,  "listings_last_30_days": 0,  "listing_activity_12m": [    {      "month": "2019-08-24",      "count": 0    }  ],  "traffic_country": "string",  "search_traffic_12m": [    0  ],  "screenshot_url": "string",  "tracking_pixels": {    "property1": [      "string"    ],    "property2": [      "string"    ]  },  "paused": true,  "scan_interval_minutes": 0,  "subscribed_at": "2019-08-24T14:15:22Z",  "tags": [    "string"  ]}

Read User Me GET

Get current user.

Competitor Lookalikes GET

Competitor lookalikes of MY product across the viewer's watched stores, paginated by Qdrant rank: pass `next_cursor` as `cursor` while `has_more`. The watchlist product and store filters narrow the page (never widen the subscription gate); `rank_limit_reached` marks the end of reachable ranks and `has_watched_stores` is false when the viewer subscribes to no store. ``product_id`` is a CORE product UUID, owner-checked via the core scope helper.