Write back, in your own words, what you found out about an incident — so the person who gets paged reads a diagnosis instead of a timestamp: 'failed because the upstream API returned 503; same failure as the last three nights; I retried twice and stopped' instead of 'check failed at 03:04'. The note appears on the incident's page in the dashboard, attributed to its author, in the order it was written. Take incident_id from list_open_incidents. SEND A NOTE WHETHER OR NOT YOU COULD FIX THE PROBLEM. The person reading the alert cannot see what you saw. With no note, an incident is indistinguishable from one nobody has looked at yet, so an agent that writes back only its successes leaves a record worse than none: every unexplained incident then reads as 'not looked at yet' when it may equally mean 'looked at and gave up'. 'Could not reproduce; gave up after two attempts' IS a finding and is worth writing. NOTES ARE APPEND-ONLY. There is no way to edit a note and no way to delete one — not merely unexposed: no route and no query exists for either, and an edit is refused by the database itself. A correction is a new note, never an edit, because a diagnosis whose history a reader cannot trust is not evidence. This is NOT a write-once resource: a second, third or tenth note on the same incident is normal and expected, and there is no conflict for writing one. The only conflict this tool has is the cap of 50 notes per incident, and reaching it means something is looping rather than diagnosing. A CLOSED incident still accepts notes, on purpose: the run that finally succeeded is usually the one that understood why the previous one did not, so refusing the note would lose the explanation exactly when it became available. Authorship is not yours to choose — every note written through this tool is stored as author 'agent', because this is the API-key surface; there is no author argument and supplying one is not possible.

Create a new LastPing API key. The plaintext key is returned ONCE and cannot be retrieved again — store it immediately in a secret manager. Set expires_at for a short-lived key.

Create a notification destination (channel) that monitors can route alerts to. Provide the fields for the chosen kind; unrelated fields are ignored. Non-email kinds are usable immediately; email kinds are created unverified and send a confirmation link that must be clicked before they can be attached to a route. Returns the new channel id — pass it to set_route.

Create a new LastPing monitor (or update an existing one if slug matches — returns 'updated' note on upsert). For heartbeat/ci monitors supply schedule_kind ('simple' requires period_s, 'cron' requires cron_expr, 'on_demand' requires neither). For http monitors supply probe_url and probe_interval_s instead — and set probe_expected_status/probe_expected_body too, because those are what define 'healthy'; a probe with neither only proves something answered. For a monitor fed by CI rather than by its own pings, set ci_provider here: it is the ONLY place it can be set, and the secret it returns is shown exactly once.

Create a status page — a single page showing the current status and recent history of a chosen set of monitors. Reach for this when the health of a monitor needs to be visible to someone who cannot log in to the project. Pages are PRIVATE unless you ask for otherwise; read the visibility parameter before making one public.

Commit, at the START of a run, to the criteria by which THAT RUN will be judged when it closes — before you can see how it turns out. This is how a run stops grading itself: once declared, a success ping whose body does not satisfy every declared criterion is recorded as a FAILED run with cause 'assertion', regardless of the exit code or what the ping claims. Call this right after your run's /start ping, before doing any work — see the assertions argument for the full, immutable contract, and get_ping_instructions' expectations_how_to for a worked example.

Permanently delete a LastPing agent from the registry by UUID. THIS DOES NOT DELETE ITS MONITORS: the agent_id foreign key on a monitor is ON DELETE SET NULL, so every monitor this agent owned survives the delete with its ping history and incidents completely intact — it just becomes unowned (agent_id cleared to null) and keeps running on its existing schedule, no longer attributed to any agent. list_monitors/get_monitor will still show it afterwards. To reattach a survivor, call update_monitor with agent_id set to a different agent's id or slug. To also remove a monitor, call delete_monitor on it separately — deleting the agent alone never does that. This action on the agent row itself cannot be undone.

Permanently delete a notification destination (channel). This cannot be undone. It also removes the destination from every monitor's routing — any event type routed ONLY to this destination stops notifying anyone, silently and with no incident to show for it. Before deleting a destination that is in use, check which monitors route to it (get_monitor returns a monitor's routes) and give those event types another destination first. To stop using a destination temporarily, prefer editing the routes with set_route and leaving the destination in place.

Permanently delete a LastPing monitor by UUID. This cannot be undone.

Permanently delete a status page. This cannot be undone, and any public URL it had stops working immediately. The monitors on the page are NOT affected — they keep running and alerting exactly as before; only the shared view of them is removed. To stop sharing without losing the page, set visibility to 'private' with update_status_page instead.

Turn a scan of a repository or a host into monitors: send every scheduled job you found, get back a diff of what was created, what already existed and what has gone missing. This is how a user gets monitored without filling in a form. PROPOSE, THEN ASK. Show the user what you found and get their agreement BEFORE calling this — it CREATES monitors. Eleven monitors created on a repository you were asked to look at are eleven things that can page a person at 03:00 and that they never agreed to, and this endpoint has no delete path to undo them with. WHAT TO SEND: a JSON array as a string in sources, one entry per job. Each entry needs source_kind and source_ref — that pair is the key this call diffs against, so source_ref must be STABLE between scans; a ref whose shape changes makes every monitor look new and duplicates the whole fleet on the next run. Kinds: 'crontab' (crontab -l, /etc/cron.d/, /etc/crontab), 'github-actions' (.github/workflows/.yml, an on.schedule.cron entry), 'k8s-cronjob' (a manifest or Helm template with kind: CronJob and a spec.schedule), 'systemd-timer' (/etc/systemd/system/*.timer, an OnCalendar= line). Send schedule_cron only when you actually read a cron expression; a workflow triggered on push has no cadence to be late against, and an invented one pages the user every quiet afternoon. Without it the monitor is created on-demand instead. READ THE TIMEZONE, DO NOT ASSUME ONE. crontab and systemd-timer fire in the HOST's local time; github-actions and k8s-cronjob evaluate their schedules in UTC. A 'crontab' or 'systemd-timer' entry carrying a schedule_cron MUST state its tz, and the zone must be READ from the host — timedatectl show -p Timezone --value, or readlink /etc/localtime where that is unavailable — not filled in as a default. A host at UTC+4 running '0 3 * * *' pings at 23:00 UTC, so a monitor recorded as tz=UTC arms its deadline about twenty hours before the job is due and opens a false incident every single day. The API cannot catch this for you: it requires that a zone be STATED, and a stated 'UTC' from a scanner that read the host is indistinguishable on the wire from a stated 'UTC' a client filled in. Send 'UTC' only when you read the host and it really is UTC. Scanning a REPOSITORY, where there is no host to read, ASK THE USER which zone those machines run in — not knowing is a question to put to them, never a reason to reach for a default. WHAT COMES BACK is a three-way diff: created (sources that had no monitor and now have one), existing (sources already monitored, returned COMPLETELY UNMODIFIED — not the name, not the schedule, not the thresholds, so an expect_every_s the user tuned by hand survives every scan), and orphaned (monitors whose source this scan did NOT report). RECONCILE NEVER DELETES, NEVER PAUSES AND NEVER EDITS ANYTHING. There is no delete path and no update path in this endpoint at all, so an orphaned monitor is still running and still alerting; treat that list as a question for the user ('this job is gone, should its monitor go too?'), never as something to act on yourself. BECAUSE OF THAT IT IS SAFE TO RE-RUN, and re-running is the point: run it nightly, on every CI build, after every deploy, and the second run creates only what has appeared since the first while orphaned becomes your drift report. A scan that runs once is a setup wizard; a scan that is safe on a schedule is drift detection. Existing monitors already carry source_kind and source_ref in list_monitors, so you can see what is already discovered without calling this.

Export existing LastPing monitors, destinations, routes, alert templates and status pages as Terraform HCL, including import blocks so they are adopted rather than recreated. Secrets are NOT exported — the output references Terraform variables you must fill in.

Get a single LastPing agent by UUID. Returns the same fields as list_agents, including its live status rollup. Use list_agents to find valid IDs, or register_agent to create one.

Get all custom alert message templates for a LastPing monitor. Returns a map of event-type (or event-type/cause) keys to template strings. Keys: 'down', 'recovery', 'fail', 'every-run', 'success', 'started', 'blocked', 'note', or 'event_type/cause' (e.g. 'down/silence'). An empty result means all alerts use the built-in plain-language defaults.

Get a single LastPing monitor by UUID. Returns the monitor's full configuration including its output assertions (the assertions field: conditions a successful run's ping body must satisfy; absent when the monitor has none) and its metric guards (the guards field: ceilings on a number the job reports about itself; absent when the monitor has none) and its alert ROUTING (the routes field: which destinations receive which event type; absent when the monitor has none). Read this before calling update_monitor with assertions or guards, and before calling set_route — every one of those three writes REPLACES a whole set, so an agent that did not read the current one first will silently drop assertions, guards or destinations somebody else configured.

Get everything needed to make a monitor actually report: the ping URL, copy-paste check-in snippets, and the three MECHANISMS for reporting, returned together. Call this right after create_monitor. CHOOSE BY WHAT THE MONITORED THING IS — read reporting_options first and pick by that, rather than defaulting to the raw curl list: how_to — the manual protocol — is the UNIVERSAL path: it works in any agent, any language, any tool, with no prerequisite, so it is the default choice for any agent this applies to. Pair it with expect_every_s (the silence floor, set via update_monitor) so an agent that quietly stops reporting opens a detected incident instead of leaving its monitor reading healthy. If you ARE Claude Code specifically, hook_install is available as an OPTIONAL SHORTCUT, not a better tier: a one-time install that binds reporting to Claude Code's own hooks (UserPromptSubmit, Stop, StopFailure), automating how_to's exact same protocol so reporting becomes a property of your event loop instead of something you must remember — and it is the only mechanism that can send every state this product models, including blocked and note. hook_install is Claude Code specific: if you are a DIFFERENT AI agent — even one with its own hook or event system, Cursor, Windsurf, Codex, a custom framework — do NOT translate its steps into your own hooks; the event semantics differ and a translated install can pass its own verification while never reporting, so use how_to instead. If what you are monitoring is launched as a command instead — a cron job, a CI step, a script, or an agent started from a shell — use run_wrapper: wrap the command with lastping run and a separate process reports for you, so nothing has to be remembered; the tradeoff is that it reports the process's own lifecycle (start, success, fail, cancel) and has no way to send blocked or note. Whichever you choose, the underlying protocol is the same: the success ping at the END of the work, the fail URL if it failed, the start ping first for long or possibly-hung runs (this enables overrun / never-finished detection), and a step (curl_step) as each stage completes so a run that wedges mid-way is caught by name rather than only when its whole budget expires. Also read expectations_how_to: before you start work, use declare_run_expectations to say how THIS run should be judged when it closes — a one-time, unchangeable commitment that replaces the run grading itself. And discovery_how_to, which is about the OTHER jobs on this host or in this repo: how to find the scheduled work nobody is watching yet and propose it, rather than monitoring only the one thing you were asked about.

Get structured run history for a monitor — both CI/CD runs and agent/heartbeat runs. Each run carries its run id (rid), kind, received_at, the progress steps reported under it (steps: seq, name, at), and the correlated incident log excerpt (incident_detail) with resolution status. A run that stalled tells you which step it reached and when it stopped moving — no need to follow links to the CI provider. steps is absent for a run that reported none — steps are matched on rid, so they appear only when the job or agent posted /step?rid= with the same run id it started with. CI-specific fields — failing step (failing_stage), triggering actor, commit SHA, run URL, branch, duration_s, outcome — are present only on runs that carried ci_meta; they are simply absent on agent/heartbeat runs. A ping with neither ci_meta nor a rid is excluded entirely. duration_ms is a SEPARATE measurement, present on ANY run (CI or agent/heartbeat) whose success ping paired with its preceding start — this is how to answer 'how long does this job normally take?' for a non-CI monitor. It is computed by LastPing from the /start->success timing, not self-reported by a provider like duration_s is; the two must not be confused as confirming each other, and either can be present without the other.

List all agents registered in the project. Returns id, slug, name, status, monitor_count and last_seen for each. status is rolled up live from the monitors the agent owns, worst first: down (a monitor is down), blocked (a monitor's run needs a human right now), late (a monitor is late), running (a monitor's run is in flight), up (healthy), pending (a monitor exists but has never reported) or idle (no monitors, or all of them paused/in maintenance). Use register_agent to create one.

List all API keys in the project. Never returns plaintext key values — only the non-secret prefix, which is enough to identify a key for revoke_api_key. Each key includes last_used_at and last_used_surface (which client — "mcp", "terraform", or "api" — most recently authenticated with it), both absent if the key has never been used. last_used_surface is best-effort client self-identification from a caller-controlled, spoofable User-Agent header: useful for answering "did my client ever successfully authenticate?", never a basis for trust or authorization decisions.

List all notification destinations (channels) in the project: email, webhook, Slack, Discord, Telegram. Use channel IDs to configure routing rules for monitors.

List recent incidents (downtime events) for a monitor. Returns newest first. An open incident has closed_at=null.

List all monitors in the authenticated LastPing project. Returns id, name, slug, status, ping_url for each. Use the tag param to filter by a single tag.

Read this agent's failure inbox: every incident currently OPEN on the monitors it owns, newest first. Call it at the START of a run, before doing the work — this is how an agent finds out what broke while it was not running, with no webhook, chat integration or mailbox to wire up. What makes the payload worth reading is NOT 'your check failed' — the run that failed already knows that. It is the context that no single failure body can contain:

• failure_signature.occurrences — how many times THIS EXACT failure has been seen on this monitor (with first_seen/last_seen, and a fingerprint you can use to correlate incidents yourself). First occurrence or fortieth repeat is the fact that decides retry versus escalate, and no amount of reasoning over one failure body can recover it.

• failed_step — the last step the run reported before it stopped. For a 'stalled' incident this is the entire diagnosis: the run is still alive and has not moved past this step.

• exit_code — the status the run exited with. 137 (SIGKILL, usually the OOM killer) and 1 are both the word 'fail' and are completely different problems.

• duration_vs_normal — a COMPARISON, not a measurement: '8.2x the typical run (41m vs 5m), from 30 archived days'. run_ms, typical_ms, ratio and days_sampled are carried too, so you can apply your own threshold and tell a 30-day norm from a 2-day one.

• cause — 'silence' and 'fail' demand opposite responses. 'fail' means the job ran and reported an error; 'silence' means it never reported at all, which usually implicates the scheduler or the host rather than the job.

• body_excerpt (the error text the failing run actually printed), run_id (line the incident up against your own logs), and ci.run_url (where the full log is, when the failure came from a CI provider). ABSENCE MEANS NO EVIDENCE — NEVER GOOD NEWS. Every enrichment degrades to ABSENT rather than erroring, so a missing field is the ordinary case, not an error. A missing duration_vs_normal means the run's duration or the monitor's baseline is unknown; it does NOT mean the run took a normal amount of time. A missing exit_code means no numeric code was reported (the ping used a word form such as /fail, or a detector opened the incident with no ping at all); it does NOT mean the job exited cleanly — and exit_code 0 is a real value this field does report, on a run that claimed success and then failed its declared expectations. A missing failure_signature or failed_step reads the same way: not known, never 'none'. Then WRITE BACK what you found with add_incident_note, passing the incident_id from the entry you acted on. Reading the inbox and saying nothing leaves the human exactly where they were.

List the project's status pages: id, slug, title, the monitors on each, visibility, and the public URL of any public page. A status page is how a monitor's health is shown to people who are not in the project — customers, or another team. This is also the read you need before update_status_page, because its check_ids REPLACE the page's monitor set.

Pause a LastPing monitor so it stops alerting (paused=true). The monitor still receives pings but does not alert.

Register a new autonomous agent in the project's agent registry, returning its id, slug and wire-up instructions in one call — so an agent can go from nothing to reporting in a single conversation. Call this ONCE per autonomous worker, not once per monitor. ATTACHMENT RULE: after registering, attach monitors to this agent by passing the returned agent_id (its id OR its slug) to create_monitor's agent_id parameter. Naming an agent that does not exist is an error (400 UNKNOWN_AGENT) — it is NEVER an implicit create, so re-running this tool with the same name is the only way to get a new agent_id to attach to. Re-registering with the same name is safe: the API derives a stable slug from name and rejects a duplicate slug rather than creating a second row.

Resume a paused LastPing monitor (paused=false). Alerting resumes on the next missed ping.

Permanently revoke an API key. The key stops authenticating immediately. This cannot be undone — a new key must be created to replace it.

Set or clear a single alert message template on a monitor. The template is validated for allowed variables before saving. Pass an empty string for template to reset that entry to the built-in default. All other existing templates are preserved (read-modify-write). Available variables: {check_name}, {event}, {status}, {cause}, {last_ping}, {schedule}, {incident_url}, {run_url}, {branch}, {commit}, {actor}, {failing_stage}, {duration}, {latency}, {status_code}, {url}, {last_step}, {step_count}, {run_duration}, {body}, {detail}. {failing_stage} is CI-only and provider-dependent: always populated on GitLab; on GitHub only if the repository webhook also subscribes to the workflow_job event; never on Jenkins, whose Notification Plugin payload carries no step detail. {body} is the triggering ping's own text (pings.body_excerpt) — it is how a 'blocked' or 'note' event's reason reaches the alert, and a custom template is the only way to control where in the message it appears.

Route a monitor's alerts for one event type to a set of destinations (channels). THIS REPLACES THE WHOLE SET for that event type — every destination you leave out stops receiving that event, including ones somebody else configured. CALL get_monitor FIRST and read its routes field: that is the monitor's current routing, and adding a destination means passing the existing ids PLUS the new one. Pass an empty channel_ids to remove all routing for the event. Destinations must be verified and enabled (email destinations must be confirmed first). Use list_destinations for IDs.

Set or clear a maintenance window on a monitor. During the window the monitor will not alert. Provide exactly one of: duration (e.g. '1h', '24h'), until (RFC 3339 timestamp), or clear=true to remove the window.

Send something through a destination right now, to move it from 'created' to 'known to work'. By default it delivers a synthetic 'LastPing test alert' immediately — use that after create_destination to confirm the credentials are right. For an EMAIL destination that is still unverified, a test alert is not what you need: an unverified email cannot be attached to a route at all, and no amount of testing changes that. Pass resend_verification=true instead to re-send the confirmation link a human must click. That is the tool to reach for when create_destination reported UNVERIFIED and the confirmation email never arrived or has expired.

Update an existing LastPing agent's name/description by UUID using merge-patch semantics: only the fields you supply are changed, and any field you omit keeps its current stored value. slug is derived from name at creation and is immutable — this can rename the agent's display name, but never its slug, so anything that already references it by slug (including monitors attached via agent_id) keeps working.

Update a notification destination's name and/or config in place. Only the fields you pass are changed. The destination kind cannot be changed — delete and recreate instead. Changing an email destination's address resets verification and sends a new confirmation email.

Update an existing LastPing monitor's schedule/config by UUID using merge-patch semantics: only the fields you supply are changed, and any field you omit keeps its current stored value. If supplied, tags replaces the full tag set on the monitor (not merged). slug is immutable and cannot be changed. This is also the tool that sets a monitor's OUTPUT ASSERTIONS (the assertions argument) — conditions the ping body of a successful run must satisfy, which is how a job that exits zero having done nothing gets caught — and its METRIC GUARDS (the guards argument) — ceilings on a number the job reports, which is how an agent that loops and burns money gets caught. Like tags, assertions and guards each REPLACE the full set. ci_provider is NOT patchable — it is immutable once set, so only its ci_workflow/ci_branch filters can be changed here; rebinding a monitor to a different CI system means deleting and recreating it.

Update a status page's title, slug, visibility, or the set of monitors on it. Only the arguments you pass are changed; anything you omit keeps its current value (this tool reads the page first and merges, so omitting check_ids can never blank the page). check_ids, when you DO pass it, REPLACES the whole monitor set — to add one monitor, pass the existing ids plus the new one, which list_status_pages gives you. Changing the slug changes the public URL and BREAKS any link already shared.