Monitors API

Monitors are the core resource in Sentro. Each monitor periodically checks a target and records whether it is reachable and responsive. Sentro supports four monitor types: HTTP, TCP, PING, and DNS.

Monitor Object

{
  "id": "cly1abc2d0001abcdef012345",
  "orgId": "org_abc123",
  "name": "Production API",
  "monitorType": "HTTP",
  "url": "https://api.example.com/health",
  "method": "GET",
  "intervalSeconds": 60,
  "timeoutSeconds": 30,
  "status": "ACTIVE",
  "expectedStatusCode": 200,
  "followRedirects": true,
  "confirmationChecks": 2,
  "headers": { "Accept": "application/json" },
  "port": null,
  "dnsRecordType": null,
  "dnsExpectedValue": null,
  "createdAt": "2025-01-15T08:30:00.000Z",
  "updatedAt": "2025-01-15T08:30:00.000Z"
}

Field	Type	Description
id	string	Unique monitor identifier
orgId	string	Organization that owns the monitor
name	string	Human-readable monitor name
monitorType	string	Monitor type: HTTP, TCP, PING, or DNS
url	string	URL (HTTP) or hostname/IP (TCP/PING/DNS)
method	string	HTTP method (GET, POST, HEAD) — HTTP only
intervalSeconds	number	Seconds between checks (minimum 10)
timeoutSeconds	number	Request timeout in seconds
status	string	ACTIVE or PAUSED
expectedStatusCode	number	Expected HTTP status code (default 200) — HTTP only
followRedirects	boolean	Whether to follow HTTP redirects — HTTP only
confirmationChecks	number	Checks in a row that must agree before an outage or recovery is recorded (default 2)
headers	object|null	Custom HTTP headers sent with each check
port	number|null	TCP port to connect to — TCP only
dnsRecordType	string|null	DNS record type (A, AAAA, CNAME, MX, TXT, NS) — DNS only
dnsExpectedValue	string|null	Expected DNS value to match — DNS only
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

---

List Monitors

GET /v1/monitors

Returns all monitors belonging to your organization.

Query Parameters

Parameter	Type	Default	Description
limit	number	50	Number of monitors to return (max 200)
offset	number	0	Number of monitors to skip for pagination

Response

{
  "data": [
    {
      "id": "cly1abc2d0001abcdef012345",
      "orgId": "org_abc123",
      "name": "Production API",
      "url": "https://api.example.com/health",
      "method": "GET",
      "intervalSeconds": 60,
      "timeoutSeconds": 30,
      "status": "ACTIVE",
      "expectedStatusCode": 200,
      "followRedirects": true,
      "confirmationChecks": 2,
      "headers": null,
      "createdAt": "2025-01-15T08:30:00.000Z",
      "updatedAt": "2025-01-15T08:30:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

⚡Try it

Fetch all monitors in your organization.

GET/v1/monitors?limit=50&offset=0

Query Parameters

limit — Number of monitors to return (max 200)

offset — Number of monitors to skip

Click ⚙ to configure your API key, then hit Send.

---

Get Monitor

GET /v1/monitors/:id

Returns a single monitor with its 10 most recent checks.

Path Parameters

Parameter	Type	Description
id	string	The monitor ID

Response

{
  "data": {
    "id": "cly1abc2d0001abcdef012345",
    "orgId": "org_abc123",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "method": "GET",
    "intervalSeconds": 60,
    "timeoutSeconds": 30,
    "status": "ACTIVE",
    "expectedStatusCode": 200,
    "followRedirects": true,
    "confirmationChecks": 2,
    "headers": null,
    "createdAt": "2025-01-15T08:30:00.000Z",
    "updatedAt": "2025-01-15T08:30:00.000Z",
    "latestChecks": [
      {
        "id": "chk_abc123",
        "monitorId": "cly1abc2d0001abcdef012345",
        "statusCode": 200,
        "latencyMs": 142,
        "isUp": true,
        "error": null,
        "checkedAt": "2025-01-15T09:30:00.000Z"
      }
    ]
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor with id 'mon_invalid' not found"
  }
}

⚡Try it

Get a single monitor with its latest checks.

GET/v1/monitors/:id

Path Parameters

:id

Click ⚙ to configure your API key, then hit Send.

---

Create Monitor

POST /v1/monitors

Creates a new monitor. The monitor begins checking immediately with status ACTIVE.

Request Body

Field	Type	Required	Description
name	string	Yes	Monitor name (1-100 characters)
monitorType	string	No	HTTP, TCP, PING, or DNS (default: HTTP)
url	string	Yes	URL (HTTP) or hostname/IP (TCP/PING/DNS)
method	string	No	HTTP method (default: GET) — HTTP only
intervalSeconds	number	No	Check interval in seconds (default: 60)
timeoutSeconds	number	No	Request timeout in seconds (default: 30)
expectedStatusCode	number	No	Expected status code (default: 200) — HTTP only
followRedirects	boolean	No	Follow redirects (default: true) — HTTP only
confirmationChecks	number	No	Checks in a row that must agree before an outage or recovery is recorded (default: 2, range: 1-10)
headers	object|null	No	Custom headers as key-value pairs — HTTP only
port	number	TCP only	TCP port (1-65535) — required for TCP
dnsRecordType	string	DNS only	A, AAAA, CNAME, MX, TXT, or NS — required for DNS
dnsExpectedValue	string	No	Expected DNS value — DNS only
bodyContains	string	No	Response body must contain this string — HTTP only
bodyNotContains	string	No	Response body must NOT contain this string — HTTP only
degradedThresholdMs	number	No	Latency above this (ms) marks monitor as degraded
groupId	string|null	No	Monitor group ID for categorization

Example: HTTP Monitor

{
  "name": "Production API",
  "url": "https://api.example.com/health",
  "method": "GET",
  "intervalSeconds": 60,
  "timeoutSeconds": 30,
  "expectedStatusCode": 200,
  "followRedirects": true,
  "confirmationChecks": 2,
  "headers": {
    "Accept": "application/json",
    "X-Custom-Header": "monitoring"
  }
}

Response 201 Created

{
  "data": {
    "id": "cly1abc2d0001abcdef012345",
    "orgId": "org_abc123",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "method": "GET",
    "intervalSeconds": 60,
    "timeoutSeconds": 30,
    "status": "ACTIVE",
    "expectedStatusCode": 200,
    "followRedirects": true,
    "confirmationChecks": 2,
    "headers": {
      "Accept": "application/json",
      "X-Custom-Header": "monitoring"
    },
    "createdAt": "2025-01-15T08:30:00.000Z",
    "updatedAt": "2025-01-15T08:30:00.000Z"
  }
}

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid monitor data",
    "details": {
      "url": ["Invalid URL format"],
      "intervalSeconds": ["Must be at least 30"]
    }
  }
}

⚡Try it

Create a new monitor that starts checking immediately.

POST/v1/monitors

Request Body

{ "name": "My API Health Check", "url": "https://api.example.com/health", "method": "GET", "intervalSeconds": 60 }

Click ⚙ to configure your API key, then hit Send.

Example: TCP Monitor

{
  "name": "Database Port Check",
  "monitorType": "TCP",
  "url": "db.example.com",
  "port": 5432,
  "intervalSeconds": 30,
  "timeoutSeconds": 10
}

Example: PING Monitor

{
  "name": "Server Ping",
  "monitorType": "PING",
  "url": "server.example.com",
  "intervalSeconds": 60,
  "timeoutSeconds": 10
}

Example: DNS Monitor

{
  "name": "DNS A Record",
  "monitorType": "DNS",
  "url": "example.com",
  "dnsRecordType": "A",
  "dnsExpectedValue": "93.184.216.34",
  "intervalSeconds": 300
}

Example: HTTP with Keyword Monitoring & Degraded Threshold

{
  "name": "API with Content Check",
  "url": "https://api.example.com/health",
  "bodyContains": "\"status\":\"ok\"",
  "bodyNotContains": "maintenance",
  "degradedThresholdMs": 2000,
  "intervalSeconds": 30
}

---

Update Monitor

PATCH /v1/monitors/:id

Updates an existing monitor. Only the fields you include in the request body will be updated.

Path Parameters

Parameter	Type	Description
id	string	The monitor ID

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Description
name	string	Updated monitor name
url	string	Updated URL to monitor
method	string	Updated HTTP method
intervalSeconds	number	Updated check interval
timeoutSeconds	number	Updated request timeout
expectedStatusCode	number	Updated expected status code
followRedirects	boolean	Updated redirect behavior
confirmationChecks	number	Updated confirmation threshold (range: 1-10)
headers	object|null	Updated custom headers (null to clear)
bodyContains	string	Updated keyword check
bodyNotContains	string	Updated negative keyword check
degradedThresholdMs	number|null	Updated degraded threshold (null to disable)
groupId	string|null	Updated monitor group

Example Request

{
  "name": "Production API (v2)",
  "intervalSeconds": 30
}

Response 200 OK

{
  "data": {
    "id": "cly1abc2d0001abcdef012345",
    "orgId": "org_abc123",
    "name": "Production API (v2)",
    "url": "https://api.example.com/health",
    "method": "GET",
    "intervalSeconds": 30,
    "timeoutSeconds": 30,
    "status": "ACTIVE",
    "expectedStatusCode": 200,
    "followRedirects": true,
    "confirmationChecks": 2,
    "headers": null,
    "createdAt": "2025-01-15T08:30:00.000Z",
    "updatedAt": "2025-01-15T09:00:00.000Z"
  }
}

⚡Try it

Update specific fields on an existing monitor.

PATCH/v1/monitors/:id

Path Parameters

:id

Request Body

{ "name": "Production API (v2)", "intervalSeconds": 30 }

Click ⚙ to configure your API key, then hit Send.

---

Delete Monitor

DELETE /v1/monitors/:id

Permanently deletes a monitor and all its associated check history.

Path Parameters

Parameter	Type	Description
id	string	The monitor ID

Response 200 OK

{
  "data": {
    "id": "cly1abc2d0001abcdef012345",
    "deleted": true
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor with id 'mon_invalid' not found"
  }
}

⚡Try it

Permanently delete a monitor and all its check history.

DELETE/v1/monitors/:id

Path Parameters

:id

Click ⚙ to configure your API key, then hit Send.