Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Resource Watches
The Watch API manages periodic resource checks, pausing, resuming, and manual triggers.
API Reference
Watch Management
List, inspect, update, and trigger watch tasks created via add_resource with watch_interval > 0. Use REST (/api/v1/watches) or ov task watch for the full set of operations. MCP provides list_watches and cancel_watch for listing and removal.
1. API Implementation Overview
Locate a task by task_id, or use to_uri when exactly one accessible task matches. Multiple Connector Watches can share a target; URI lookup then returns 409 Conflict and requires a task_id. If both keys are supplied, they must identify the same task or the request returns 400.
Operations:
- List (
GET /api/v1/watches) — returns{tasks, total}; pass?active_only=trueto filter; pass?to_uri=...to collapse to a single-task lookup - Show (
GET /api/v1/watches/{task_id}) — inspect one task; optional?to_uri=performs a cross-key sanity check - Update (
PATCH /api/v1/watches/{task_id}orPATCH /api/v1/watches?to_uri=...) — partial update ofwatch_interval,is_active,reason,instruction.is_activeis independent ofwatch_interval: changeis_activeto pause/resume without losing the configured cadence. - Delete (
DELETE /api/v1/watches/{task_id}orDELETE /api/v1/watches?to_uri=...) - Trigger (
POST /api/v1/watches/{task_id}/triggerorPOST /api/v1/watches/trigger?to_uri=...) — fire-and-forget refresh; returns immediately while the underlying re-ingest runs in the background
Code Entry Points:
openviking/server/routers/watches.py— REST router for/api/v1/watchescrates/ov_cli/src/commands/watch.rs—ov task watchCLI subcommand groupopenviking/server/mcp_endpoint.py— MCPlist_watches/cancel_watchtools and thewatch_interval/toparameters onadd_resourceopenviking/resource/watch_manager.py:WatchManager— task persistence and scheduling primitives
2. Interface and Parameter Description
For every single-task endpoint the path {task_id} can be replaced with a ?to_uri= query argument. The CLI <key> argument is auto-classified: any value starting with viking:// routes to the by-URI path, anything else is treated as a task ID (other URI schemes such as http:// are rejected locally to avoid silent 404s).
PATCH /watches body (all fields optional; at least one is required)
| Field | Type | Description |
|---|---|---|
| watch_interval | float | New cadence in minutes. Must be > 0; use is_active=false to pause without losing the cadence. |
| is_active | bool | Toggle activation without losing the cadence (pause / resume). |
| reason | string | Update the recorded reason for the watch. |
| instruction | string | Update the semantic processing instruction. |
Unrecognized fields are rejected with HTTP 400 and INVALID_ARGUMENT (extra="forbid" on the request model). Fields left unset preserve their current values.
3. Usage Examples
HTTP API
# List active watch tasks (drop ?active_only to include paused ones)
curl -s "http://localhost:1933/api/v1/watches?active_only=true" \
-H "X-API-Key: your-key"
# Pause a watch without losing its cadence
curl -X PATCH "http://localhost:1933/api/v1/watches/<task_id>" \
-H "X-API-Key: your-key" -H "Content-Type: application/json" \
-d '{"is_active": false}'
# Trigger an immediate refresh (fire-and-forget; returns before the re-ingest finishes)
curl -X POST "http://localhost:1933/api/v1/watches/<task_id>/trigger" \
-H "X-API-Key: your-key"
# Resolve by URI instead of task ID
curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/guide.md" \
-H "X-API-Key: your-key"
Python SDK
The following uses SyncHTTPClient; await each call with AsyncHTTPClient.
watches = client.list_watches(active_only=True)
client.update_watch(to_uri="viking://resources/guide.md", is_active=False)
client.trigger_watch(to_uri="viking://resources/guide.md")
client.delete_watch(to_uri="viking://resources/guide.md")
TypeScript SDK
const watches = await client.listWatches({ activeOnly: true });
await client.updateWatch(
{ toUri: "viking://resources/guide.md" },
{ isActive: false },
);
await client.triggerWatch({ toUri: "viking://resources/guide.md" });
await client.deleteWatch({ toUri: "viking://resources/guide.md" });
Go SDK
watches, err := client.ListWatches(ctx, &openviking.ListWatchesOptions{
ActiveOnly: true,
})
updated, err := client.UpdateWatch(ctx, openviking.UpdateWatchOptions{
ToURI: "viking://resources/guide.md",
IsActive: openviking.Bool(false),
})
triggered, err := client.TriggerWatch(ctx, openviking.WatchRef{
ToURI: "viking://resources/guide.md",
})
deleted, err := client.DeleteWatch(ctx, openviking.WatchRef{
ToURI: "viking://resources/guide.md",
})
_, _, _, _ = watches, updated, triggered, deleted
CLI
The following examples use the ov task watch subcommands:
# List active watches (drop --active-only to include paused ones)
ov task watch ls --active-only
# Inspect a single watch (key may be either a viking:// URI or a task_id)
ov task watch show viking://resources/guide.md
# Pause / resume without losing the cadence
ov task watch pause viking://resources/guide.md
ov task watch resume viking://resources/guide.md
# Update the cadence (or any combination of --active / --reason / --instruction)
ov task watch update viking://resources/guide.md --interval 30
# Trigger an immediate fire-and-forget refresh
ov task watch trigger viking://resources/guide.md
# Remove a watch task entirely
ov task watch rm viking://resources/guide.md
Response
Listing tasks returns:
{
"status": "ok",
"result": {
"tasks": [
{
"task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
"path": "https://example.com/guide.md",
"source_type": "url",
"to_uri": "viking://resources/guide.md",
"parent_uri": "viking://resources",
"reason": "keep documentation current",
"instruction": "",
"watch_interval": 30,
"build_index": true,
"summarize": false,
"processor_kwargs": {},
"created_at": "2026-07-24T10:00:00",
"last_execution_time": null,
"last_task_id": null,
"last_status": null,
"last_error": null,
"next_execution_time": "2026-07-24T10:30:00",
"is_active": true,
"account_id": "default",
"user_id": "default",
"original_role": "user"
}
],
"total": 1
}
}
source_type is optional provenance metadata. Explicit Connector add_type values take
precedence (for example, tos or feishu_project); native imports report feishu, git,
url, or local. Legacy or unclassified watches return null.
Before the first run, last_task_id, last_status, and last_error are null. After a run,
last_task_id points to the corresponding ingestion task (and can remain null for preflight
failures), while last_status is completed, failed, or cancelled. On failure,
last_error contains a credential-redacted error limited to 500 characters. Use
ov task status <last_task_id> for the ingestion task details.
Getting one task and a successful update return the same task object directly in result. Delete and trigger return:
{
"status": "ok",
"result": {
"task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
"to_uri": "viking://resources/guide.md",
"deleted": true
}
}
{
"status": "ok",
"result": {
"task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
"to_uri": "viking://resources/guide.md",
"scheduled": true
}
}
scheduled=true only confirms that background execution was scheduled. It does not mean
re-ingestion has completed; read the task again until last_execution_time changes, then inspect
last_status and last_error.
MCP
list_watches() # one line per task; URIs only, no task_ids surfaced
cancel_watch(to_uri="viking://resources/guide.md") # idempotent removal by URI
Removing a Watch removes its schedule, not the imported resource. MCP exposes listing and removal. To create a Watch, use add_resource with watch_interval. Use the CLI or REST API to pause, resume, trigger, or change the cadence of an existing Watch. Re-importing does not update an existing Watch.
Related Documentation
- Resources - create resources with watch_interval
- Background Tasks - inspect background processing