MonitorHQ API Documentation

Authentication

MonitorHQ uses Bearer tokens for authentication. You can use either a JWT token (from login) or an API key.

Authorization: Bearer <your-token-or-api-key>

API keys start with pp_ and can be generated from the dashboard.

Rate Limits

API requests are rate limited to prevent abuse:

Endpoint	Limit
Authentication	5 requests/minute
Demo Check	10 requests/minute
All other endpoints	100 requests/minute

Demo

GET /check Public

Description

Perform a one-time URL check without authentication. Perfect for testing.

Query Parameters

url

string

required

URL to check (must include protocol)

Response Example

{
  "url": "https://example.com",
  "status": "up",
  "statusCode": 200,
  "responseTime": 245,
  "timestamp": "2024-01-15T10:30:00Z"
}

🧪 Try It

URL to check

Response

Authentication

POST /auth/register Register a new user

Request Body

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "John Doe"
}

Response

{
  "message": "User registered successfully",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": 1, "email": "user@example.com" }
}

POST /auth/login Login and get token

Request Body

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe",
    "plan": "free"
  }
}

GET /auth/me Auth Required Get current user

Response

{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "plan": "free"
}

Monitors

GET /monitors Auth Required List all monitors

Response

[
  {
    "id": 1,
    "name": "Production API",
    "url": "https://api.example.com",
    "type": "http",
    "interval": 60,
    "status": "up",
    "uptime_7d": 99.95
  }
]

POST /monitors Auth Required Create a new monitor

Request Body

{
  "name": "Production API",
  "url": "https://api.example.com/health",
  "type": "http",
  "interval": 60,
  "timeout": 30,
  "method": "GET",
  "expected_status": 200
}

GET /monitors/:id Auth Required Get monitor details

Path Parameters

id

integer

Monitor ID

PUT /monitors/:id Auth Required Update monitor

Request Body

Same fields as create, all optional.

DELETE /monitors/:id Auth Required Delete monitor

Response

{
  "message": "Monitor deleted"
}

Incidents

GET /incidents Auth Required List incidents

Query Parameters

status	string	Filter by status (investigating, identified, monitoring, resolved)
severity	string	Filter by severity (minor, major, critical)
monitor_id	integer	Filter by monitor
resolved	boolean	Filter resolved/unresolved

POST /incidents Auth Required Create manual incident

Request Body

{
  "title": "API Degradation",
  "description": "Increased latency on API endpoints",
  "severity": "major",
  "status": "investigating",
  "monitor_id": 1
}

GET /incidents/:id Auth Required Get incident details with updates

Response

{
  "id": 1,
  "title": "API Degradation",
  "status": "investigating",
  "severity": "major",
  "updates": [
    {
      "id": 1,
      "status": "investigating",
      "message": "Looking into the issue",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

PUT /incidents/:id Auth Required Update incident

Request Body

{
  "title": "Updated Title",
  "severity": "critical",
  "status": "identified"
}

POST /incidents/:id/acknowledge Auth Required Acknowledge incident

Response

{
  "message": "Incident acknowledged",
  "incident": { ... }
}

POST /incidents/:id/resolve Auth Required Resolve incident

Request Body

{
  "message": "Issue has been resolved"
}

POST /incidents/:id/updates Auth Required Add status update

Request Body

{
  "status": "identified",
  "message": "Root cause identified. Working on fix."
}

Teams

POST /teams Auth Required Create a team

Request Body

{
  "name": "Engineering Team"
}

Response

{
  "id": 1,
  "name": "Engineering Team",
  "slug": "engineering-team-a1b2c3",
  "owner_id": 1,
  "created_at": "2024-01-15T10:30:00Z"
}

GET /teams Auth Required List your teams

Response

[
  {
    "id": 1,
    "name": "Engineering Team",
    "slug": "engineering-team-a1b2c3",
    "my_role": "owner",
    "member_count": 5
  }
]

GET /teams/:id Auth Required Get team details

Response

{
  "id": 1,
  "name": "Engineering Team",
  "my_role": "owner",
  "members": [
    {
      "user_id": 1,
      "email": "owner@example.com",
      "role": "owner"
    }
  ],
  "pending_invites": []
}

PUT /teams/:id Auth Required Update team (owner/admin)

Request Body

{
  "name": "New Team Name"
}

DELETE /teams/:id Auth Required Delete team (owner only)

Response

{
  "message": "Team deleted"
}

POST /teams/:id/invite Auth Required Invite member (owner/admin)

Request Body

{
  "email": "newmember@example.com",
  "role": "member"
}

Valid roles: admin, member, viewer

Response

{
  "id": 1,
  "email": "newmember@example.com",
  "role": "member",
  "invite_url": "/api/v1/teams/accept-invite/abc123..."
}

DELETE /teams/:id/members/:userId Auth Required Remove member (owner/admin)

Response

{
  "message": "Member removed"
}

PUT /teams/:id/members/:userId Auth Required Update member role (owner only)

Request Body

{
  "role": "admin"
}

POST /teams/accept-invite/:token Auth Required Accept team invite

Response

{
  "message": "Successfully joined team",
  "team": {
    "id": 1,
    "name": "Engineering Team"
  }
}