---
title: "Create TCP Monitor"
description: "Creates a new TCP monitor."
---

`POST /api/tcp-monitors`

## Authentication

Requires a valid session.

- Header: `Authorization: Bearer <token>`

## Request Body

```json
{
  "customerId": "11111111-1111-4111-8111-111111111111",
  "name": "Redis Primary",
  "hostname": "redis.deinkunde.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

```bash
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.deinkunde.com",
    "port": 6379,
    "status": "active",
    "checkInterval": 60,
    "timeoutSeconds": 30,
    "config": { "expectBanner": "+PONG" }
  }'
```

## Response

```json
{
  "id": 300,
  "publicId": "44444444-4444-4444-8444-444444444444",
  "organizationId": 1,
  "customerId": 10,
  "name": "Redis Primary",
  "hostname": "redis.deinkunde.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