Watches API

Method	Path	Auth	Purpose
GET	/watches	Token	List the caller's watches.
POST	/watches	Token	Create a watch. The owner is taken from your token, never the body.
GET	/watches/:id	Token	Fetch one owned watch.
PUT	/watches/:id	Token	Replace one owned watch. Id and owner are not client-settable.
DELETE	/watches/:id	Token	Delete one owned watch. Run history is kept.
GET	/watches/:id/runs	Token	Run history, newest first. Accepts ?limit=.
POST	/watches/:id/run	Token	Run this watch now, ignoring its schedule. Returns the outcome.
POST	/watches/run-all	Token	Run all of the caller's enabled watches now. 409 if one is already in flight.

All routes are scoped to the identity in your token.

List

curl -s https://<your-host>/watches -H "authorization: Bearer $TOKEN"

{ "watches": [ { "id": "framework-releases", "name": "Framework stable releases", "...": "..." } ] }

Create

curl -s -X POST https://<your-host>/watches \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "id": "framework-releases",
    "name": "Framework stable releases",
    "sources": [{ "type": "rss", "value": "https://example.com/blog/feed.xml", "trust": "official" }],
    "schedule": "0 */6 * * *",
    "condition": "A new stable version is released. Ignore release candidates and betas.",
    "channels": ["telegram"],
    "threshold": 0.6,
    "weakThreshold": 0.4,
    "enabled": true
  }'

Returns 201 with the stored watch. The body is validated against the full watch schema; failures return 400 with the offending fields.

Caution

ownerId in the body is ignored — the owner is always your token’s identity. Watch ids are global, so an id already used by any account returns 409.

Get, replace, delete

curl -s https://<your-host>/watches/framework-releases -H "authorization: Bearer $TOKEN"
curl -s -X PUT https://<your-host>/watches/framework-releases -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{ ...full watch... }'
curl -s -X DELETE https://<your-host>/watches/framework-releases -H "authorization: Bearer $TOKEN"

PUT is a full replacement, not a patch: send the complete watch. The id comes from the path.

Deleting removes the watch definition. Its run history is kept.

Run history

curl -s "https://<your-host>/watches/framework-releases/runs?limit=20" -H "authorization: Bearer $TOKEN"

Newest first. Each record carries the outcome, the summary and evidence, the model’s reasoning, per-source errors, collection counts, the models consulted and the corroborating trust tier. See Runs and feedback.

Run now

curl -s -X POST https://<your-host>/watches/framework-releases/run -H "authorization: Bearer $TOKEN"

Runs the watch immediately, ignoring its schedule, and returns the result synchronously:

{
  "result": {
    "watchId": "framework-releases",
    "outcome": "nothing-new",
    "collected": 10,
    "fresh": 0,
    "notificationsSent": 0,
    "sourceErrors": [],
    "collection": { "attempted": 1, "collected": 10, "extracted": 10, "failed": 0 }
  }
}

Note

This call blocks for as long as the run takes — collection plus one or more model calls, so seconds to minutes. Set a generous client timeout. A disabled watch returns the disabled outcome rather than an error.

Run all

curl -s -X POST https://<your-host>/watches/run-all -H "authorization: Bearer $TOKEN"

Runs every enabled watch you own, ignoring schedules, and returns a summary plus per-watch outcomes:

{
  "summary": { "total": 4, "ran": 3, "skipped": 1, "failed": 0, "notified": 1 },
  "outcomes": [ { "watchId": "framework-releases", "status": "ran", "result": { "...": "..." } } ]
}

Only one run-all per owner may be in flight; a second returns 409. Watches are processed sequentially by default to respect shared model rate limits, so this can take a while.