Update to Postman

{
  "name": "api-monitoring",
  "description": "Creates, schedules, and manages Postman Monitors — recurring checks against a live API — triggers ad hoc runs, inspects job/run history to diagnose failures, and hosts self-hosted execution runners for monitors on a private network. Use when the user asks to \"set up a monitor,\" \"run this monitor now,\" \"check monitor results,\" \"pause/resume a monitor,\" or \"set up a runner for our internal APIs.\" Covers `postman monitor` (create, update, delete, list, get, pause, resume, run, jobs, runs) and `postman runner` (start, list, regions).",
  "included_files": [],
  "skill_md_contents": "---\nname: api-monitoring\ndescription: Creates, schedules, and manages Postman Monitors — recurring checks against a live API — triggers ad hoc runs, inspects job/run history to diagnose failures, and hosts self-hosted execution runners for monitors on a private network. Use when the user asks to \"set up a monitor,\" \"run this monitor now,\" \"check monitor results,\" \"pause/resume a monitor,\" or \"set up a runner for our internal APIs.\" Covers `postman monitor` (create, update, delete, list, get, pause, resume, run, jobs, runs) and `postman runner` (start, list, regions).\n---\n\n# API Monitoring\n\n## Overview\n\nA Monitor is a recurring, scheduled check against a live API. The CLI now\nowns its full lifecycle: `monitor create`/`update`/`delete`/`pause`/`resume`\nmanage the schedule and configuration, `monitor list`/`get` discover and\ninspect existing ones, `monitor run` triggers an ad hoc run, and `monitor\njobs`/`monitor runs` inspect what actually happened during a run. There is\nno remaining task here that has to go through the Postman app.\n\n`postman runner` is a separate, infrastructure-level concern: it starts a\nself-hosted execution agent so Monitor runs can reach APIs that live behind\na private network Postman's cloud can't reach directly, and it lists the\nvalues (Postman regions or self-hosted runner ids) that `monitor\ncreate`/`update --runner` accepts.\n\n## Creating and scheduling a monitor\n\n`monitor create -c <collectionId>` is the minimum — name defaults to the\nlinked collection's own name. Workspace comes from `-w`, or falls back to\nthe workspace named in the local `.postman/resources.yaml` manifest;\nwithout either, creation fails. `--schedule <cron>` plus `--timezone`\n(defaults to the host machine's zone) set when it fires; `--runner`\n(repeatable) says where from — a Postman region name (`postman runner\nregions`) or a self-hosted runner's id (`postman runner list`), and both\ncan be mixed in the same monitor. `--notify-email` (repeatable) and\n`--notification-limit` control failure alerts. The run itself is shaped by\nthe same options as a collection run — `--retry` (service caps at 2),\n`--timeout`, `--delay`, `--strict-ssl`/`--insecure`,\n`--follow-redirects`/`--block-redirects`, and dataset iteration via\n`--dataset-id`/`--dataset-view-id`/`--iteration-count`/\n`--iteration-strategy`. Creation triggers an immediate run by default; pass\n`--no-run-now` to skip that.\n\n## Updating, pausing, and deleting\n\n`monitor update <monitorId>` takes the same schedule/runner/notification/\nrun-option flags as `create`, plus `--clear-notifications` to wipe every\nrecipient. It cannot change the linked collection or environment — delete\nand recreate the monitor instead — and it does not pause or resume; use\n`monitor pause`/`monitor resume` for that. `monitor delete <monitorId>`\nprompts for confirmation unless `-y`/`--yes` is passed, and is permanent.\n\n## Discovering and inspecting monitors\n\n`monitor list` filters by `-w`/`-c`/`--environment`/`--owner`/`--team`/\n`--active`. `--runner <id>` filters to a *self-hosted* runner id (not a\nPostman region) and can't be combined with the other filters. Page with\n`--limit`/`--cursor`; `--offset` is accepted by the service but silently\nignored, so the CLI rejects it locally rather than returning a page that\nlooks right but isn't — use `--cursor` from the previous page's response.\n`--columns` picks which fields show, `-f`/`--filter` matches on name within\nthe page already returned (not a server-side search), and `--sort name|active`\norders it. `monitor get <monitorId>` shows one monitor's full configuration.\n\n## Triggering a run\n\n`monitor run <monitorId>` runs an existing Monitor synchronously and prints\nthe result — useful in CI to get a pass/fail right after a deploy rather\nthan waiting for the next scheduled tick. `-t/--timeout` (default 15\nminutes) caps how long the CLI waits for completion; a timeout hit here is\nthe CLI giving up on waiting, not the Monitor itself failing. `--async`\nsubmits the run and returns immediately with its job id and Postman URL\ninstead of waiting at all — reach for this over a long `-t` when the caller\ndoesn't need the verdict inline. `--json` prints only the verdict as JSON,\nfor scripting. `-x/--suppress-exit-code` overrides the default\nfail-on-failed-run exit code, for a caller that wants to see failures\nwithout breaking a pipeline step.\n\n## Diagnosing a run\n\n`monitor jobs list <monitorId>` lists a monitor's recent jobs; `monitor jobs\nget <jobId>` reports one job's terminal state and its per-region run\noutcomes — a monitor with runners in multiple regions runs once per region\nper job. `monitor runs get <runId>` goes one level deeper: which test\nassertions ran during one attempt, which failed, and why. Reach for these\ninstead of re-running blind after a `-t` timeout, or whenever the task is\nexplaining *why* a monitor failed rather than just that it did.\n\n## Private (self-hosted) runners\n\nA private runner — the CLI's `runner regions` calls the same thing a\n\"private-runner\" value — is an agent you run inside your own network so\nMonitor traffic originates there instead of from Postman's cloud IPs. Reach\nfor one only when the monitored API sits behind a VPN, firewall, or on-prem\nnetwork that Postman's cloud can't reach directly; a public API should just\nuse a Postman region (`--runner us-east`, etc.) since that needs no\ninfrastructure of your own to run or maintain.\n\n`runner start --id <id> --key <key>` (from the Postman app) registers a\nrunner that executes monitor runs from your own infrastructure instead of\nPostman's cloud. Extra\nflags cover the runner's own networking: `--region eu` for EU residency,\n`--proxy`/`--egress-proxy`/`--egress-proxy-authz-url` for outbound routing,\n`--ssl-extra-ca-certs` for a private CA, and `--metrics`/`--metrics-port`\nfor a health-check endpoint. Analytics are sent by default; `--no-report-events`\nopts out. `runner list` shows the team's registered self-hosted runners —\nfeed an id from here into `monitor create/update --runner` or `monitor list\n--runner`. `runner regions` lists the Postman-region and private-runner\nvalues valid for `--runner` on `monitor create`/`update`, including a\nstatic IP where one is configured — check here before guessing a region\nstring.\n\n## Critical Rules\n\n1. **`update` can't move a monitor to a different collection or environment,\n   and doesn't pause/resume it.** Delete and recreate for the former; use\n   `pause`/`resume` for the latter.\n2. **A `monitor run -t` timeout is a wait cap, not a monitor failure.**\n   Don't report \"the monitor failed\" from a timeout without checking\n   `monitor jobs get`/`monitor runs get` (or the Postman app) for what the\n   run actually did after the CLI gave up waiting — or avoid the wait\n   entirely with `--async`.\n3. **`--runner` on `monitor create`/`update` takes a region name or a\n   self-hosted runner id — check `runner regions`/`runner list` before\n   guessing a string,** and don't suggest `runner start` unless the target\n   API genuinely isn't reachable from Postman's cloud.\n4. **`monitor list --offset` doesn't work — use `--cursor`,** and\n   `--runner` there can't be combined with the other filters.\n5. **`monitor delete` is permanent.** Confirm intent before passing `-y` to\n   skip its prompt.\n\n## Verification\n\nState the monitor/job/run id and the actual pass/fail result or\nconfiguration change, not just that the command exited. For `run`, state\nwhether it completed synchronously or was submitted `--async` (a job id is\nnot yet a verdict — resolve it with `monitor jobs get` before reporting a\nresult). If a self-hosted runner was started, confirm it registered (the\nPostman app, or `runner list`, shows it as connected) before assuming\nmonitor runs will route through it.\n"
}