# 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](https://imsu.io/docs/agents.md). All the docs in one file: [https://imsu.io/llms-full.txt](https://imsu.io/llms-full.txt).

## What imsu.io does

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.

## Which way to connect

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](https://imsu.io/docs/mcp). The OAuth flow in detail: [Authentication](https://imsu.io/docs/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](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](https://imsu.io/docs/api)) or to the MCP server at `https://imsu.io/mcp`.

Check an API key before you use it:

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

```json
{
  "user": {
    "id": "01a1c6de-b461-7461-919d-3d918e658f67",
    "email": "you@example.com",
    "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.

## What only the user can do

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](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).

## Good habits

- 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.

## When you see X, do Y

`/api/v1` errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 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.

| You see | Where | It means | Do this |
|---|---|---|---|
| `401` with `resource_metadata` in `WWW-Authenticate` | `/mcp` | No token, or one that is unknown, expired or revoked | MCP client: start OAuth from the `resource_metadata` URL, or refresh the access token first if you have a refresh token. Headless: ask the user for an API key. [Authentication](https://imsu.io/docs/mcp#authentication) |
| `401` [unauthorized](https://imsu.io/docs/api#unauthorized) | `/api/v1` | No API key, or one that is unknown, revoked or expired, or the account is suspended; OAuth tokens are refused here too | Ask the user for a valid API key from Settings → API keys |
| `403` with `error="insufficient_scope"` | `/mcp` | The user allowed this app to read only, and the tool changes monitors | Tell the user, then run the authorization again asking for `monitors:read monitors:write`. [Insufficient scope](https://imsu.io/docs/mcp#insufficient-scope) |
| Tool error "This API key can only read monitors…" | `/mcp` | A read-only API key called a tool that changes monitors | Ask the user for a key with read and write access |
| `403` [insufficient-scope](https://imsu.io/docs/api#insufficient-scope) | `/api/v1` | A read-only key tried to change monitors | Ask the user for a key with read and write access |
| `403` [monitor-limit-reached](https://imsu.io/docs/api#monitor-limit-reached), or a tool error about the plan's limit | both | Every monitor the plan allows is in use (paused ones count) | Tell the user the limit. They can delete a monitor they no longer need. Don't retry |
| `400` [validation-failed](https://imsu.io/docs/api#validation-failed), or a tool error "Invalid arguments…" | both | A field, parameter or header is wrong; each one is named | Fix the named fields and send again |
| `404` [not-found](https://imsu.io/docs/api#not-found), or a tool error "No monitor with id…" | both | No such monitor in this account | List the monitors to find the right id |
| Tool error "Monitor … already checks …" or "A heartbeat named … already exists" | `/mcp` | A monitor for the same target exists (heartbeats: one with the same name) | Use that monitor. Pass `allow_duplicate: true` only if the user wants a second one |
| `409` [idempotency-key-in-use](https://imsu.io/docs/api#idempotency-key-in-use) | `/api/v1` | The first request with this `Idempotency-Key` is still running | Wait a few seconds and retry with the same key and body |
| `422` [idempotency-key-reused](https://imsu.io/docs/api#idempotency-key-reused) | `/api/v1` | The key was used before with a different body | Use a new key for a new request |
| `413` [body-too-large](https://imsu.io/docs/api#body-too-large) or [body too large](https://imsu.io/docs/mcp#body-too-large) | both | The body is over 64 KB (`/api/v1`) or 256 KB (`/mcp`) | Send a smaller body; a monitor takes a few hundred bytes |
| `415` [unsupported-media-type](https://imsu.io/docs/api#unsupported-media-type), or `415` "Unsupported charset" | both | The body isn't JSON, or not in a charset the server reads | Send JSON with `Content-Type: application/json` (UTF-8) |
| `429` [rate-limited](https://imsu.io/docs/api#rate-limited) or [too many requests](https://imsu.io/docs/mcp#rate-limits) | both | The credential sent too many requests this minute | Wait the number of seconds in `Retry-After`, then retry |
| `405` with `Allow: POST` | `/mcp` | `GET` and `DELETE` open and close streams, which this server doesn't use | Nothing: send messages with `POST` |
| `400` from `/mcp` with a JSON-RPC error | `/mcp` | A batch (a JSON array), or an unknown `MCP-Protocol-Version` | Send one message per request with a version the server named at `initialize` |
| `500` or `503` | both | Something failed on imsu.io's side | Retry later. On `/api/v1`, quote the `X-Request-Id` header if you report it |

## Where to go next

- [MCP server](https://imsu.io/docs/mcp): client setup, the tools, examples
- [Authentication](https://imsu.io/docs/authentication): OAuth 2.1 for MCP clients, request by request
- [REST API](https://imsu.io/docs/api): API keys and every `/api/v1` operation
- [OpenAPI document](https://imsu.io/api/v1/openapi.json) of the REST API