API Documentation — monitorca

Introduction

The Monitorca API lets you programmatically manage your service statuses, events, and public addresses. Use it to integrate your CI/CD pipeline, monitoring agents, or internal tooling directly with your status pages.

The API is REST-based, accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes.

Base URL

https://monitorca.com/api

Endpoints Overview

GET /applications

GET /applications/{applicationId}/services

POST /ping/{applicationId}/{serviceId}

GET /applications/{applicationId}/events

GET /applications/{applicationId}/events/{eventId}

POST /applications/{applicationId}/events

PUT /applications/{applicationId}/events/{eventId}

DELETE /applications/{applicationId}/events/{eventId}

GET /applications/{applicationId}/events/{eventId}/addresses

POST /applications/{applicationId}/events/{eventId}/addresses

PUT /applications/{applicationId}/events/{eventId}/addresses/{addressId}

DELETE /applications/{applicationId}/events/{eventId}/addresses/{addressId}

Authentication

All API requests are authenticated using Bearer tokens. Create an API key from Dashboard → Developers. Include it in every request via the Authorization header.

curl https://monitorca.com/api/applications/{appId}/events \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

API keys can be scoped to specific applications, or granted access to all applications. Configure this when creating or editing a key.

Errors

The API returns standard HTTP status codes and a JSON body with an error key on failure.

Code	Meaning
`401`	Missing or invalid API key.
`403`	API key lacks access to the requested application, or API updates are disabled.
`404`	Resource not found.
`422`	Validation error — check the returned `errors` object.
`500`	Server error — please try again or contact support.

Error Response Example

{
  "error": "API key does not have access to this application"
}

Rate Limits

API requests are rate-limited per API key on a per-minute sliding window. The default limit is 60 requests per minute (1 per second). If you exceed the limit you will receive a 429 Too Many Requests response.

Rate-Limited Response 429

{
  "error": "Rate limit exceeded. You are allowed 60 requests per minute. Contact support to increase your limit."
}

Response Headers

Every API response includes rate-limit headers so you can monitor your usage:

Header	Description
`X-RateLimit-Limit`	Your maximum allowed requests per minute.
`X-RateLimit-Remaining`	How many requests remain in the current window.
`Retry-After`	Seconds until the current window resets (only on `429` responses).

Best Practices

If you receive a 429 response, wait for the number of seconds indicated in the Retry-After header before retrying.
Use exponential back-off with jitter for automatic retries.
Batch or space out requests to stay well within the limit.

Need a higher limit? Contact support and we can increase your per-minute allowance.

Ping (Update Service Status)

Update the operational status of a service. A new uptime event is created only when the status changes.

POST /ping/{applicationId}/{serviceId}?status={status}

Query Parameters

Name	Type		Description
status	string	optional	One of `up`, `degraded`, `down`. Defaults to `up`.

Request

curl -X POST \
  "https://monitorca.com/api/ping/{applicationId}/{serviceId}?status=up" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "success": true,
  "service_id": "aBcDeFgHiJkLmNoP",
  "status": "up",
  "changed": false
}

List Applications

Retrieve all applications accessible by this API key. Returns only applications the key has been granted access to, or all applications if the key has the "all applications" flag.

GET /applications

This is a read-only endpoint and is not affected by the "API updates disabled" setting.

Request

curl "https://monitorca.com/api/applications" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "applications": [
    {
      "id": "aBcDeFgHiJkLmNoP",
      "name": "Production API",
      "created_at": "2026-01-15T08:00:00.000000Z",
      "updated_at": "2026-03-07T12:00:00.000000Z"
    },
    {
      "id": "qRsTuVwXyZ1234Ab",
      "name": "Staging Environment",
      "created_at": "2026-02-01T10:00:00.000000Z",
      "updated_at": "2026-03-06T15:30:00.000000Z"
    }
  ]
}

List Services

Retrieve all services for an application, including each service's current operational status.

GET /applications/{applicationId}/services

This is a read-only endpoint and is not affected by the "API updates disabled" setting.

Request

curl "https://monitorca.com/api/applications/{appId}/services" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "services": [
    {
      "id": "sVc1aBcDeFgHiJkL",
      "name": "Web Application",
      "status": "up",
      "service_group_id": null,
      "created_at": "2026-01-15T08:00:00.000000Z",
      "updated_at": "2026-03-07T12:00:00.000000Z"
    },
    {
      "id": "sVc2mNoPqRsTuVwX",
      "name": "Database",
      "status": "degraded",
      "service_group_id": null,
      "created_at": "2026-01-15T08:00:00.000000Z",
      "updated_at": "2026-03-07T14:20:00.000000Z"
    }
  ]
}

Status Values

Value	Meaning
`up`	Service is operating normally.
`degraded`	Service is experiencing degraded performance.
`down`	Service is experiencing an outage.

List Events

Retrieve all events for an application, ordered by newest first. Optionally filter by status or type.

GET /applications/{applicationId}/events

Query Parameters

Name	Type		Description
status	string	optional	Filter by `open` or `resolved`.
type	string	optional	Filter by `incident`, `maintenance`, or `info`.

Request

curl "https://monitorca.com/api/applications/{appId}/events?status=open" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "events": [
    {
      "id": "xK9mRpQ2wL4nY7vA",
      "application_id": "aBcDeFgHiJkLmNoP",
      "name": "Database connectivity issues",
      "type": "incident",
      "status": "open",
      "all_services": false,
      "scheduled_start": null,
      "scheduled_end": null,
      "created_at": "2026-03-07T12:00:00.000000Z",
      "updated_at": "2026-03-07T12:00:00.000000Z",
      "services": [...],
      "public_addresses": [...]
    }
  ]
}

Get Event

Retrieve a single event including its linked services and public addresses.

GET /applications/{applicationId}/events/{eventId}

Request

curl "https://monitorca.com/api/applications/{appId}/events/{eventId}" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "event": {
    "id": "xK9mRpQ2wL4nY7vA",
    "name": "Database connectivity issues",
    "type": "incident",
    "status": "open",
    "all_services": false,
    "services": [...],
    "public_addresses": [...]
  }
}

Create Event

Create a new event (incident, maintenance, or info) for an application.

POST /applications/{applicationId}/events

Body Parameters

Name	Type		Description
name	string	required	Event title. Max 255 characters.
type	string	optional	`incident` (default), `maintenance`, or `info`. Maintenance and info require Pro plan.
status	string	optional	`open` (default) or `resolved`.
all_services	boolean	required	If `true`, the event affects all services. Otherwise, provide `service_ids`.
service_ids	string[]	optional	Array of service IDs to associate. Ignored when `all_services` is `true`.
scheduled_start	datetime	optional	ISO 8601 start time. Only used for `maintenance` events.
scheduled_end	datetime	optional	ISO 8601 end time. Must be after `scheduled_start`.

Request

curl -X POST \
  "https://monitorca.com/api/applications/{appId}/events" \
  -H "Authorization: Bearer mca_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Scheduled maintenance window",
    "type": "maintenance",
    "all_services": true,
    "scheduled_start": "2026-03-08T02:00:00Z",
    "scheduled_end": "2026-03-08T04:00:00Z"
  }'

Response 201

{
  "event": {
    "id": "nT3xWpK8bM2rJ5qA",
    "name": "Scheduled maintenance window",
    "type": "maintenance",
    "status": "open",
    "all_services": true,
    "scheduled_start": "2026-03-08T02:00:00.000000Z",
    "scheduled_end": "2026-03-08T04:00:00.000000Z",
    "services": [],
    "public_addresses": []
  }
}

Update Event

Update any field on an existing event. Only include the fields you want to change.

PUT /applications/{applicationId}/events/{eventId}

Body Parameters

Same parameters as Create Event, all optional. Include only what you want to change.

Request — Resolve an event

curl -X PUT \
  "https://monitorca.com/api/applications/{appId}/events/{eventId}" \
  -H "Authorization: Bearer mca_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

Response 200

{
  "event": { /* full event object */ }
}

Delete Event

Permanently delete an event and all of its associated public addresses and service links.

DELETE /applications/{applicationId}/events/{eventId}

Request

curl -X DELETE \
  "https://monitorca.com/api/applications/{appId}/events/{eventId}" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "success": true
}

List Public Addresses

Retrieve all public address updates for a given event, ordered newest first.

GET /applications/{applicationId}/events/{eventId}/addresses

Request

curl "https://monitorca.com/api/applications/{appId}/events/{eventId}/addresses" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "addresses": [
    {
      "id": "hG5kLmPqRsT2wX9v",
      "application_id": "aBcDeFgHiJkLmNoP",
      "app_event_id": "xK9mRpQ2wL4nY7vA",
      "timestamp": "2026-03-07T12:30:00.000000Z",
      "header": "Investigating",
      "text": "We are aware of the issue and investigating.",
      "created_at": "2026-03-07T12:30:00.000000Z",
      "updated_at": "2026-03-07T12:30:00.000000Z"
    }
  ]
}

Create Public Address

Post a new public-facing status update to an event.

POST /applications/{applicationId}/events/{eventId}/addresses

Body Parameters

Name	Type		Description
timestamp	datetime	required	ISO 8601 datetime for the update.
header	string	optional	Short heading, e.g. "Investigating", "Resolved". Max 255 characters.
text	string	required	The body text of the public-facing update.

Request

curl -X POST \
  "https://monitorca.com/api/applications/{appId}/events/{eventId}/addresses" \
  -H "Authorization: Bearer mca_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-03-07T12:30:00Z",
    "header": "Investigating",
    "text": "We are aware of the issue and actively investigating the root cause."
  }'

Response 201

{
  "address": {
    "id": "hG5kLmPqRsT2wX9v",
    "timestamp": "2026-03-07T12:30:00.000000Z",
    "header": "Investigating",
    "text": "We are aware of the issue and actively investigating the root cause."
  }
}

Update Public Address

Edit an existing public address. Only include the fields you want to change.

PUT /applications/{applicationId}/events/{eventId}/addresses/{addressId}

Body Parameters

Same parameters as Create Address, all optional.

Request

curl -X PUT \
  "https://monitorca.com/api/applications/{appId}/events/{eventId}/addresses/{addressId}" \
  -H "Authorization: Bearer mca_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "header": "Resolved", "text": "The issue has been resolved." }'

Response 200

{
  "address": { /* full address object */ }
}

Delete Public Address

Permanently remove a public address from an event.

DELETE /applications/{applicationId}/events/{eventId}/addresses/{addressId}

Request

curl -X DELETE \
  "https://monitorca.com/api/applications/{appId}/events/{eventId}/addresses/{addressId}" \
  -H "Authorization: Bearer mca_YOUR_API_KEY"

Response 200

{
  "success": true
}