Submit an action to the Impri human-approval inbox.

The action appears in the operator's web and mobile inbox as a card with a title, formatted preview, and optional tap-to-edit fields. The operator approves or rejects with one tap; you poll for the decision with impri_await_decision.

Returns { action_id, status: "pending", inbox_url }. Save action_id — you need it for all follow-up calls.

Example — send a draft Reddit reply for review: kind: "reddit.comment" title: "Reply: Why is resume advice so conflicting?" preview: { format: "markdown", body: "The advice conflicts because different advisors optimise for different audiences..." } target_url: "https://reddit.com/r/cscareerquestions/comments/..." editable: ["preview.body"] // lets the reviewer tweak wording before approving

Poll until the human approves, rejects, or the timeout elapses.

Checks GET /actions/:id every 5 seconds and returns as soon as the action leaves the pending state.

Decision meanings: "approved" — proceed with the action; any reviewer edits are included in preview/payload "rejected" — abort; respect the decision and do not proceed "expired" — the approval window closed; create a new action if the task is still relevant

On timeout the action stays pending in the inbox. Call impri_inbox_status to check queue depth and consider pausing further submissions.

Typical usage:

1. impri_push_action → get action_id

2. impri_await_decision(action_id) → wait for human decision

3. If approved: execute the action, then impri_report_result(action_id, "executed")

Report whether you successfully executed an approved action.

Closes the audit loop — the operator sees 'executed' or 'execute_failed' in the inbox alongside the original action and decision. Always call this after attempting an approved action, even on failure.

Statuses: "executed" — action was carried out successfully "execute_failed" — execution attempt failed (include the error in detail)

Check how many actions are waiting for human decisions.

Returns the pending count and a brief list of pending action titles. Call this before starting a large batch of tasks — if the inbox is backed up, pause and let the operator catch up to avoid actions expiring before they are reviewed.

Create a watcher that monitors external sources (RSS feeds, Reddit, URL diffs) and delivers matching items to the approval inbox or a webhook.

The watcher runs on the schedule you specify, deduplicates items by URL/content-hash, and delivers only new matches. The first run establishes a baseline and does not generate alerts.

Example — watch an RSS feed for AI-related news: spec: { name: "AI launches radar", kind: "rss", config: { url: "https://openai.com/news/rss.xml" }, keywords: ["launch", "gpt-", "voice"], keywords_none: ["funding", "benchmark"], min_score: 1, schedule: { every: "8h", jitter: "4h" } }

Returns { watcher_id, name, kind, status, next_run_at }.

List all configured watchers, optionally filtered by status.

Returns the watcher count and a summary line per watcher (id, name, kind, status). Use this to audit what is being monitored, check for degraded watchers, or find a watcher_id for further operations.

List all available watcher presets with their parameters.

Presets are pre-configured watcher templates for common sources (Hacker News, Reddit, GitHub, npm, YouTube, arXiv, etc.). Each preset has an id, a human-readable title, required and optional params, and a default schedule.

Call this first to discover which preset fits your monitoring goal, then use impri_create_watcher_from_preset to create the watcher by supplying only the preset_id and param values. No deep knowledge of watcher config schemas is needed.

Example output: Community: - hn-front-page: "Hacker News Front Page" (rss) — no params required - reddit-keyword: "Reddit – Keyword Search" (reddit_search) — params: query, [subreddit]

Create a watcher from a preset template by supplying the preset id and param values.

Presets handle all watcher config construction — URL building, keyword setup, SSRF validation — so you only provide the param values listed by impri_list_watcher_presets.

The schedule defaults to the preset's recommended interval but can be overridden. The name defaults to "{preset title}: {primary param value}" if omitted.

Returns { watcher_id, name, kind, status, next_run_at }.

Examples:

Watch the HN front page (no params needed): preset_id: "hn-front-page" params: {}

Watch a subreddit for new posts: preset_id: "reddit-subreddit" params: { subreddit: "MachineLearning" }

Watch a GitHub repo for new releases, check every 2 hours: preset_id: "github-releases" params: { owner: "fastify", repo: "fastify" } schedule: { every: "2h" }

Watch HN for keyword with a custom min_points threshold: preset_id: "hn-keyword" params: { keyword: "rust programming", min_points: "25" }