imsu.io for AI agents

This page is for AI agents first and people second. It says what imsu.io does, how an agent connects to a user's account, what only the user can do, and what to do about each error.

Everything here is also Markdown: https://imsu.io/docs/agents.md. All the docs in one file: https://imsu.io/llms-full.txt.

imsu.io checks a user's services on a schedule and alerts them by email, Slack or Telegram when one goes down and when it is back up.

• http monitors request a URL with GET or HEAD and check the status code and, optionally, a keyword in the body.
• port monitors open a TCP connection to host:port. A reverse check alerts when a port that should be closed (a database, say) accepts connections.
• heartbeat monitors wait for a job (cron, backup, worker) to request its ping URL. They are down when the pings stop.
• The free plan allows 10 monitors, each checked at most every 5 minutes (300 seconds). There is no credit card and no paid plan to buy yet.

An agent can list, read, create, change, pause, resume and delete the monitors of the user's account. It acts as the user, with the access the user gave it.

1. You are an MCP client (Claude, Claude Code, Cursor, VS Code, ChatGPT or another client that supports remote MCP servers with OAuth): connect to the MCP server at https://imsu.io/mcp. Your client starts OAuth when the server answers 401; the user signs in to imsu.io in the browser and allows access. Setup per client: MCP server. The OAuth flow in detail: Authentication.
2. You run in a shell, a script or CI, or your MCP client can't do OAuth: ask the user for an API key. They create one at https://imsu.io/settings, under API keys. Send it as Authorization: Bearer imsu_pat_… to the REST API at https://imsu.io/api/v1 (REST API) or to the MCP server at https://imsu.io/mcp.

Check an API key before you use it:

curl https://imsu.io/api/v1/me -H "Authorization: Bearer $IMSU_API_KEY"

{
  "user": {
    "id": "01a1c6de-b461-7461-919d-3d918e658f67",
    "email": "[email protected]",
    "displayName": "Ada"
  },
  "accountId": "01a1c6de-b48f-783c-9a6e-3e17ba91dbdc",
  "credential": {
    "kind": "api_key",
    "id": "01a1c6de-b511-7f9d-900e-99d409cc4d1d",
    "name": "Deploy script",
    "scopes": ["monitors:read", "monitors:write"],
    "expiresAt": null
  }
}

A key whose scopes lack monitors:write can only read.

An agent can't do these. Ask the user to do them in the browser, then carry on.

• Sign up. The user creates an account at https://imsu.io/register with an email address and a password. There is no API for it.
• Sign in. Never ask for or type the user's password. Sign-in has a bot check, and OAuth exists so the agent never sees the password.
• Approve access. The consent page at https://imsu.io/authorize asks the user, not the agent. The user may allow reading only.
• Create, see or revoke API keys. Only in Settings. A key is shown once, when it is created.
• Disconnect an app. Settings → Connected apps, or the app revokes its own tokens.
• Change alert channels, status pages, the account or the plan. Only in the web app. Higher limits are set by imsu.io staff; there is no self-service upgrade.

Also not possible: monitoring addresses that aren't reachable from the public internet (private or local networks), and reading check history or incidents through the API (get_monitor shows the open incident and the last 24 hours' uptime).

• Find monitor ids with list_monitors or GET /api/v1/monitors. Never guess an id.
• Intervals are in seconds: 300 is 5 minutes. They can't be shorter than the account's minimum (get_account_limits, GET /api/v1/limits).
• Ask the user before deleting a monitor; say which one. Deleting can't be undone; pausing can.
• create_monitor refuses a second monitor for the same target (heartbeats: with the same name) unless you pass allow_duplicate: true. Pass it only when the user wants a second one.
• On the REST API, send an Idempotency-Key with each create, so a retry can't create two monitors.

/api/v1 errors are RFC 9457 problem details whose type links to their section of the docs. /mcp answers HTTP errors the same way; problems inside a tool call come back as a tool result with isError: true and a sentence that says how to fix the call.

• MCP server: client setup, the tools, examples
• Authentication: OAuth 2.1 for MCP clients, request by request
• REST API: API keys and every /api/v1 operation
• OpenAPI document of the REST API