Skip to content

docs(api): document Watch Management endpoints from #2110#2123

Merged
qin-ctx merged 2 commits into
volcengine:mainfrom
r266-tech:docs-watches-mgmt-from-2110
May 20, 2026
Merged

docs(api): document Watch Management endpoints from #2110#2123
qin-ctx merged 2 commits into
volcengine:mainfrom
r266-tech:docs-watches-mgmt-from-2110

Conversation

@r266-tech
Copy link
Copy Markdown
Contributor

Description

Documents the Watch Management surface introduced in #2110 (REST /api/v1/watches/*, the ov task watch CLI subcommand group, and the MCP list_watches / cancel_watch tools). All three control planes are net-new and currently undocumented in docs/{en,zh}/api/02-resources.md, where users land for everything watch_interval-related.

The new section follows the API documentation writing guide: Implementation Overview / Code Entry Points / Interface and Parameter Description / Usage Examples (HTTP + CLI + MCP). EN and ZH are mirrored.

Related Issue

Documents the changes from #2110 (RFC #2104 — Watch Management API).

Type of Change

  • Documentation update

Changes Made

  • docs/en/api/02-resources.md: insert a ### Watch Management section between ### add_resource and ### add_skill (~93 lines added)
  • docs/zh/api/02-resources.md: mirrored Chinese section (~93 lines added)

Specifically captured:

  • 5 REST routes (list / show / update / delete / trigger), each with both {task_id} and ?to_uri= variants
  • PATCH /watches body schema with field semantics (notably watch_interval must be > 0; is_active orthogonal to the cadence for pause/resume; extra="forbid" → 422)
  • ov task watch subcommands (ls / show / rm / pause / resume / update / trigger) with the <key> auto-classification (viking:// URI vs task_id)
  • MCP minimum closure (list_watches, cancel_watch) and an explicit note that pause / resume / trigger / update are intentionally CLI/REST-only
  • Cross-reference back to add_resource as the watch-creation entry point

Testing

  • No code changes; docs-only PR
  • Verified endpoint paths, verbs, body fields, validator messages, CLI subcommand names, and CLI flag names against openviking/server/routers/watches.py and crates/ov_cli/src/commands/watch.rs at HEAD
  • EN/ZH parity check: same operations, same field semantics, same examples

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • My changes generate no new warnings

@github-actions
Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪
🏅 Score: 100
🧪 No relevant tests
🔒 No security concerns identified
✅ No TODO sections
🔀 No multiple PR themes
⚡ No major issues detected

@github-actions
Copy link
Copy Markdown

PR Code Suggestions ✨

No code suggestions found for the PR.

@qin-ctx qin-ctx merged commit 27ed1e1 into volcengine:main May 20, 2026
3 checks passed
@github-project-automation github-project-automation Bot moved this from Backlog to Done in OpenViking project May 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants