# JustMonitorIt API

Everything you do in the JustMonitorIt dashboard you can also do from your
own code: create and change monitors, read results and uptime, acknowledge
incidents, manage contacts. There are three ways in, all over HTTPS and all
authenticated with the same API tokens:

| Surface | Endpoint | Use it for |
|---|---|---|
| [REST](rest.md) | `https://dash.justmonitorit.com/api/v1` | Scripts, CI pipelines, infrastructure as code. JSON over HTTP; an [OpenAPI 3.1 document](https://dash.justmonitorit.com/api/v1/openapi.json) describes every operation. |
| [GraphQL](graphql.md) | `https://dash.justmonitorit.com/api/v1/graphql` | Dashboards and tools that want several related things (monitors with their uptime and open incidents) in one request. |
| [MCP](mcp.md) | `https://dash.justmonitorit.com/api/v1/mcp` | AI assistants (Claude, Cursor, VS Code and other MCP clients) that should look at your monitors and incidents, or change them. |

GraphQL and MCP run the same operations as REST, so the same roles,
validation, plan limits, rate limits and audit log apply whichever you use.

## Quick start

1. **Create a token.** In the dashboard, open **Settings → API tokens**,
   choose a name, a role (`viewer` to read, `member` to also change
   monitors, incidents and contacts) and an expiry, and copy the token. It
   starts with `jmi_` and is shown only once. See
   [Authentication](authentication.md).

2. **Check it works.** `GET /token` describes the token, including the id
   of its organisation:

   ```sh
   export JMI_TOKEN=jmi_...   # your token
   curl -s https://dash.justmonitorit.com/api/v1/token \
     -H "Authorization: Bearer $JMI_TOKEN"
   ```

   ```json
   {
     "token": { "id": "tok_01j9...", "name": "CI", "role": "member", "prefix": "Ab3dE9xY", "...": "..." },
     "org": { "id": "org_01j9...", "name": "Acme" },
     "effective_role": "member"
   }
   ```

3. **Call the API.** Everything belonging to your organisation is under
   `/orgs/{org}`. List the monitors that are down:

   ```sh
   ORG=org_01j9...           # from step 2
   curl -s "https://dash.justmonitorit.com/api/v1/orgs/$ORG/monitors?status=down" \
     -H "Authorization: Bearer $JMI_TOKEN"
   ```

More in [Examples](examples.md): creating monitors, pausing them during a
deploy, acknowledging incidents and exporting uptime, in curl, Python and
JavaScript.

## Pages

- [Authentication](authentication.md): API tokens, roles, expiry and
  revocation.
- [REST conventions](rest.md): JSON, ids, errors, pagination, idempotency,
  concurrency and rate limits.
- [REST reference](generated/rest-reference.md): every operation a token can
  call, with parameters, bodies and responses.
- [Monitor kinds](monitor-kinds.md): the `spec` of each of the eight
  monitor kinds.
- [Examples](examples.md): complete recipes.
- [Terraform and Pulumi](terraform.md): monitors and contacts as code, with
  Terraform, OpenTofu or Pulumi.
- [GraphQL](graphql.md): the schema, queries and mutations.
- [MCP server](mcp.md): connecting an AI assistant.

For language models, [`/llms.txt`](https://dash.justmonitorit.com/llms.txt)
lists these pages as Markdown and
[`/llms-full.txt`](https://dash.justmonitorit.com/llms-full.txt) has all of
them in one file.

## Concepts

- **Organisation.** Monitors, contacts and incidents belong to an
  organisation. A token works on one organisation only.
- **Monitor.** One check of one target (an HTTP URL, a host, a port, a
  certificate, a domain, a mail server), run every `interval_s` seconds
  from at least two **locations** (`lon1`, `fra1`, `nyc1`, ...;
  `GET /locations` lists them). A monitor's status is `up`, `down`,
  `degraded`, `no_data`, `unknown` or `paused`. It only goes down when
  failures are confirmed from a quorum of locations by more than one probe,
  so one bad network path does not page you.
- **Incident.** Opened when a monitor goes down or degraded, resolved when
  it recovers. It records a timeline (status changes, notifications,
  acknowledgements, notes) and the cause.
- **Contact.** Where notifications go: an email address, a mobile number
  (SMS), a phone number we call and read the alert to (a mobile or a
  landline; a call uses 2 SMS credits, 4 outside the UK, Ireland, the US
  and Canada, and more for numbers that cost more to call), a Pushover user, a Discord webhook, a PagerDuty service (an
  Events API v2 integration key: down opens a PagerDuty incident and the
  recovery resolves it), a Slack channel (an incoming webhook), a Microsoft
  Teams channel (a Workflows webhook, `secret.webhook_url`) or a webhook
  (JSON posted to your own HTTPS endpoint). Email, SMS, phone call and
  Teams contacts are verified with a code (a phone call contact gets a call
  that reads it out; a Teams contact gets it posted to the channel) before
  they receive alerts. A webhook is sent
  nothing until its host has the TXT record shown on the contact
  (`config.txt_name`, `config.txt_value`), which proves you control the
  domain; then "Check again" (`verify/send`) activates it.

## Support

Questions and problems: support@justmonitorit.com. Include the
`X-Request-Id` header of the response (also `request_id` in error bodies);
it identifies the request in our logs.