Topics API

Create and manage monitoring topics via REST. All endpoints require a Bearer API key.

Scope

These endpoints manage every monitor in your account, including monitors created on the website or mobile app. API-created monitors appear in the same monitor list and follow your account's notification preferences. The same plan limits and monitoring credits apply across all platforms. Configure a webhook in settings or with PUT /api/v1/webhook to receive update notifications in your own application.

Topic types (on creation, detected from name)

web_page, if name is a valid HTTP or HTTPS URL, AyeWatch monitors that specific page.
subject, if name is plain text, AyeWatch monitors that keyword/subject across the internet.
platform, if source is supplied, AyeWatch follows one platform feed, such as an X profile or a subreddit, and alerts on new posts.

Method	Path	Description
POST	/api/v1/topics	Create a topic
GET	/api/v1/topics	List topics (paginated)
GET	/api/v1/topics/:id	Get a topic
PUT	/api/v1/topics/:id	Update a topic
DELETE	/api/v1/topics/:id	Delete a topic

POST/api/v1/topics

Create a new monitoring topic.

Active topics are limited by your plan's active-topic limit and allowed intervals, and turning a topic on needs enough monitoring credits for one check. Accounts also have a default storage limit of 3,000 topics, counting every topic you have, active or paused, created through the API or in the app.

Request Body (JSON)

Name	Type	Required	Description
name	string	No	Required unless web_page_urls or source is supplied. A valid URL (e.g. "https://openai.com/news") to monitor a page, or plain text (e.g. "OpenAI announcements") to monitor a subject. Topic type is auto-detected.
interval	string	No	Required for custom monitoring. Check interval. One of: "0_5_hours", "1_hour", "6_hours", "12_hours", "1_day", "2_days", "3_5_days", "7_days", "14_days", "30_days", "182_days", "365_days". Your plan must unlock the interval you choose.
description	string	No	What should alert you. Describe the change you care about, e.g. "Tell me when a new AI model drops."
is_active	boolean	No	Whether to start monitoring immediately. Default: true.
verification_level	string	No	How much corroboration is required before you're alerted: "instant", "balanced", or "verified". Defaults to "instant" for pages and "balanced" for subjects.
type	string	No	"subject", "web_page", or "platform". Detected from name or source on creation if omitted; preserved on edits.
web_page_urls	string[]	No	Pages to monitor together. Replaces the source list. Your plan's page limit applies.
source	object	No	A platform source: {"mode": "x_profile", "inputs": {"handle": "https://x.com/openai"}}. Creates a platform monitor. See Platform sources below.
monitoring_mode	string	No	"auto" lets AyeWatch choose the interval; "custom" uses interval. Defaults to custom.
auto_min_interval / auto_max_interval	string \| null	No	Optional interval bounds for automatic monitoring.
timezone	string	No	IANA timezone, for example Asia/Kolkata.
triggers	array	No	Precise conditions to alert on, instead of relying on the description alone. See Triggers below. Max 4.

Platform sources

A platform monitor follows one feed. Its first check records what is already there; later checks alert on new posts. Send source instead of name: the monitor is named after its source, for example "X profile: x.com/openai", unless you supply a name. Account inputs take links, not bare names or handles, so send https://x.com/openai rather than @openai; it is stored as the canonical link. The mode can't be changed after creation, and platform monitors don't accept triggers.

Mode	Platform	Follows	Inputs	Credits per check
x_search	X	Search	query	2
x_profile	X	Profile	handle	2
x_community	X	Community	community	2
reddit_search	Reddit	Search	query	1
reddit_subreddit	Reddit	Subreddit	subreddit	1
reddit_subreddit_search	Reddit	Search in subreddit	subreddit, query	1
reddit_user	Reddit	User	username	1
youtube_channel_videos	YouTube	Channel videos	channel	1
youtube_search	YouTube	Search	query	1
youtube_shorts	YouTube	Shorts	channel	2
youtube_lives	YouTube	Live streams	channel	2
youtube_community_posts	YouTube	Community posts	channel	2
linkedin_post_search	LinkedIn	Post search	query	2
linkedin_company_posts	LinkedIn	Company posts	company	2
linkedin_person_posts	LinkedIn	Person posts	profile	8
linkedin_jobs	LinkedIn	Jobs	query, location (optional)	1
instagram_search	Instagram	Search	query	2
instagram_hashtag	Instagram	Hashtag	hashtag	2
tiktok_profile	TikTok	Profile	handle	1
tiktok_search	TikTok	Search	query	1
tiktok_hashtag	TikTok	Hashtag	hashtag	2

Every mode also accepts an optional filter input of up to 200 characters, shown in the app as "Only alert me about". AI judges each new post against it, and only matching posts alert you. A filter adds 1 credit per check.

Example, monitor a platform source

shell

curl -X POST https://ayewatch.ai/api/v1/topics \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "mode": "reddit_subreddit",
      "inputs": { "subreddit": "https://www.reddit.com/r/LocalLLaMA/", "filter": "new open-weight model releases" }
    },
    "interval": "1_hour"
  }'

Triggers (optional)

A trigger states a condition in structured form. When you supply them, AyeWatch still falls back to interpreting your description for anything the triggers don't cover.

entity, what is being watched, e.g. "GPT-5".
attribute, the property of it, e.g. "price".
op, one of <, <=, >, >=, =, changed, crossed_above, crossed_below.
value, must be numeric for the comparison operators (everything except changed).
source_url, optional, restricts the trigger to one source.

Example, alert on a precise condition

shell

curl -X POST https://ayewatch.ai/api/v1/topics \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NVIDIA H100 pricing",
    "interval": "6_hours",
    "verification_level": "verified",
    "triggers": [
      {
        "entity": "H100 80GB",
        "attribute": "price",
        "op": "<",
        "value": 25000,
        "value_type": "number"
      }
    ]
  }'

Example, monitor a URL

shell

curl -X POST https://ayewatch.ai/api/v1/topics \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "https://openai.com/news",
    "interval": "1_hour"
  }'

Example, monitor a subject / keyword

shell

curl -X POST https://ayewatch.ai/api/v1/topics \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI product announcements",
    "interval": "1_day"
  }'

Response, 201 Created

json

{
  "data": {
    "id": 1042,
    "name": "https://openai.com/news",
    "description": null,
    "is_active": true,
    "interval": "1_hour",
    "created_at": "2026-08-03T12:00:00Z"
  }
}

Create, read, list, and update responses contain only id, name, description, interval, is_active, and created_at. Use id to fetch, edit, or delete the monitor. is_active is true for an active monitor and false for a paused monitor. Successful changes are saved immediately; monitoring may take a few minutes to start.

GET/api/v1/topics

List all monitors for the authenticated account, paginated.

Query Parameters

Name	Type	Required	Description
page	number	No	Page number. Default: 1.
page_size	number	No	Results per page. Max: 100. Default: 20.
is_active	boolean	No	Filter by active status. Pass "true" or "false".
interval	string	No	Filter by interval. One of: "1_hour", "6_hours", etc. Legacy values on older topics are also accepted as a filter.
created_after	string (ISO 8601)	No	Only topics created after this datetime.
created_before	string (ISO 8601)	No	Only topics created before this datetime.

Request

shell

curl "https://ayewatch.ai/api/v1/topics?page=1&page_size=10&is_active=true" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

Response, 200 OK

json

{
  "data": [
    {
      "id": 1042,
      "name": "https://openai.com/news",
      "description": null,
      "is_active": true,
      "interval": "1_hour",
      "created_at": "2026-03-08T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "has_more": false
  }
}

GET/api/v1/topics/:id

Retrieve a single topic by ID.

Responses contain the monitor's basic details.

Request

shell

curl https://ayewatch.ai/api/v1/topics/1042 \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

Response, 200 OK

json

{
  "data": {
    "id": 1042,
    "name": "https://openai.com/news",
    "description": null,
    "is_active": true,
    "interval": "1_hour",
    "created_at": "2026-03-08T12:00:00Z"
  }
}

PUT/api/v1/topics/:id

Update a topic. Send only the fields you want to change.

Omitted settings are preserved. A name, description, or source change clears generated alert rules unless you supply replacement triggers. Platform monitors use source; is_active and timezone can be updated independently. List your account monitors, then use a returned ID to edit a monitor created on any platform.

Request Body (JSON), all fields optional

Name	Type	Required	Description
name	string	No	New subject name or first page URL. Other page URLs are preserved. Use type to change the monitor type.
description	string	No	New description.
interval	string	No	New check interval. One of: "1_hour", "6_hours", etc. Your plan must unlock the interval you choose.
is_active	boolean	No	Enable or disable the topic.
verification_level	string	No	New verification level: "instant", "balanced", or "verified".
type	string	No	"subject" or "web_page". A monitor can't be changed to or from "platform".
web_page_urls	string[]	No	Pages to monitor together. Replaces the source list. Your plan's page limit applies.
source	object	No	A platform monitor's new inputs and filter, with the same mode. Replaces all inputs. Renames the monitor unless name is also supplied.
monitoring_mode	string	No	"auto" lets AyeWatch choose the interval; "custom" uses interval. Defaults to custom.
auto_min_interval / auto_max_interval	string \| null	No	Optional interval bounds for automatic monitoring.
timezone	string	No	IANA timezone, for example Asia/Kolkata.
triggers	array	No	Replaces the existing triggers. Send an empty array to clear them; omit the field to leave them untouched.

The request must contain at least one of these fields. Unknown fields are rejected with a 400 rather than silently ignored.

Request

shell

curl -X PUT https://ayewatch.ai/api/v1/topics/1042 \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interval": "6_hours", "is_active": false}'

Response, 200 OK

json

{
  "data": {
    "id": 1042,
    "name": "https://openai.com/news",
    "description": null,
    "is_active": false,
    "interval": "6_hours",
    "created_at": "2026-03-08T12:00:00Z"
  }
}

DELETE/api/v1/topics/:id

Permanently delete a topic and its schedule. This action cannot be undone.

Request

shell

curl -X DELETE https://ayewatch.ai/api/v1/topics/1042 \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

Response, 200 OK

json

{
  "data": {
    "deleted": true
  }
}