Create TCP Monitor

POST /api/tcp-monitors

Authentication

Requires a valid session.

• Header: Authorization: Bearer <token>

Request Body

{
  "customerId": "11111111-1111-4111-8111-111111111111",
  "name": "Redis Primary",
  "hostname": "redis.example.com",
  "port": 6379,
  "status": "active",
  "checkInterval": 60,
  "timeoutSeconds": 30,
  "config": {
    "expectBanner": "+PONG"
  }
}

Fields

• customerId (number | string, required)
  • Accepts either the internal numeric customer ID or the public customer UUID.
• name (string, required, max 255 chars)
• hostname (string, required, max 253 chars)
  • Must be a hostname only (no protocol like https://, no path like /status).
• port (number, required, 1–65535)
  • Unlike other monitor types, TCP monitors have no default port — you must specify the port to connect to.
• status (string, optional)
  • Allowed: active, maintenance, disabled, paused, inactive (paused/inactive are normalized to disabled). Defaults to active.
• checkInterval (number, optional, 1–1440 minutes)
  • Defaults to 30.
• timeoutSeconds (number, optional, 1–60)
  • Defaults to 30.
• allowedCheckCountryCodes (string[], optional)
  • Restricts checks to these ISO-3166-1 alpha-2 country codes.
• managementType (string, optional)
  • Allowed: managed, self_service. Only organization writers may set this; other callers always get managed.
• config (object, optional)
  • Stored as the monitor's config JSON. TCP monitors carry no credentials — the only supported key is expectBanner.

config (worker-supported keys)

• expectBanner (string, optional, max 255 chars)
  • If set, the worker verifies that the raw bytes received right after the TCP handshake contain this substring (e.g. +PONG for Redis, 220 for an SMTP banner). If omitted, the check only verifies that the TCP handshake succeeds.

cURL

curl -X POST "https://YOUR_DOMAIN/api/tcp-monitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "11111111-1111-4111-8111-111111111111",
    "name": "Redis Primary",
    "hostname": "redis.example.com",
    "port": 6379,
    "status": "active",
    "checkInterval": 60,
    "timeoutSeconds": 30,
    "config": { "expectBanner": "+PONG" }
  }'

Response

{
  "id": 300,
  "publicId": "44444444-4444-4444-8444-444444444444",
  "organizationId": 1,
  "customerId": 10,
  "name": "Redis Primary",
  "hostname": "redis.example.com",
  "port": 6379,
  "status": "active",
  "managementType": "managed",
  "checkInterval": 60,
  "timeoutSeconds": 30,
  "notificationEmail": null,
  "notificationPhoneNumber": null,
  "lastCheckedAt": null,
  "createdAt": "2026-02-26T12:00:00.000Z",
  "updatedAt": "2026-02-26T12:00:00.000Z",
  "config": {
    "expectBanner": "+PONG"
  }
}

Errors

• 400 invalidHostname — hostname must be a valid hostname (no protocol, no path)
• 400 Invalid request body (e.g. missing/out-of-range port, invalid config keys)
• 400 Invalid Customer identifier
• 401 Unauthorized
• 403 Forbidden (e.g. readonly without self-service permission, self-service quota reached, or global supporter)
• 404 Customer not found