Skip to Content
Uptimeify Docs
MonitorsFtp monitors

Create FTP Monitor

Creates a new FTP monitor.

POST /api/ftp-monitors

Authentication

This endpoint requires an API token:

Authorization: Bearer <token>

Request Body

  • customerId (required, number | string): internal numeric customer ID or customer publicId UUID
  • name (required, string)
  • hostname (required, string): Must be a hostname (no protocol, no path).
  • port (optional, number | null): If omitted/null, the worker uses a default port.
  • status (optional): active, maintenance, disabled (also accepts inactive and normalizes it to disabled)
  • checkInterval (optional, number): Minutes (min: 1, max: 60)
  • timeoutSeconds (optional, number): Seconds (min: 1, max: 60)
  • checkMode (optional, string): protocol | tcp. Defaults to protocol.
    • In tcp mode the monitor performs a bare TCP port-reachability check: ftpConfig is not required and is not stored. In protocol mode the full FTP login check runs (existing behavior).
  • ftpConfig (optional, object): FTP connection options (stored as JSON)
    • Required (user + password) unless checkMode is tcp.

ftpConfig

The monitoring worker reads these keys:

  • user (optional, string): Defaults to anonymous
  • password (optional, string): Defaults to anonymous@
  • secure (optional, boolean | "implicit"):
    • false (default): plain FTP
    • true: explicit TLS
    • "implicit": implicit TLS (worker defaults port to 990 when port is not provided)
{
  "customerId": "6764e84f-f02a-43e6-a46d-cecaec556723",
  "name": "FTP Availability",
  "hostname": "claas.sh",
  "port": 21,
  "status": "active",
  "checkInterval": 5,
  "timeoutSeconds": 30,
  "ftpConfig": {
    "user": "root",
    "password": "exampleRoot",
    "secure": "explicit"
  }
}

Duplicates

If this customer already has a monitor with the same hostname (case and a trailing dot do not count), port and checkMode, the request is refused with 409 and data.code monitorAlreadyExists. data.existingId and data.existingPublicId name the existing monitor. Send "allowDuplicate": true to create the second monitor anyway (for example with a different interval or other alert channels).

  • allowDuplicate (boolean, optional, default false): create the monitor even if it is a duplicate. Not stored.
{
  "statusCode": 409,
  "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.",
  "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" }
}

Limit per target host

An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but www.example.com and example.com are different hosts. Once the limit is reached, the request is refused with 403 and data.code targetHostMonitorLimitReached. data.host names the normalized host, data.limit the limit. "allowDuplicate": true does not lift the limit. The same check runs when a PATCH changes the hostname. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with 403 and data.code targetHostPlatformLimitReached; data.host and data.limit are set as above, and the message does not reveal how many monitors other organizations have.

{
  "statusCode": 403,
  "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this host or contact support to raise the limit.",
  "data": { "code": "targetHostMonitorLimitReached", "host": "example.com", "limit": 100 }
}

Example (cURL)

BASE_URL="https://uptimeify.io"
TOKEN="<your-api-token>"

curl -X POST \
  "$BASE_URL/api/ftp-monitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"6764e84f-f02a-43e6-a46d-cecaec556723","name":"FTP Availability","hostname":"claas.sh","port":21,"status":"active","checkInterval":5,"timeoutSeconds":30,"ftpConfig":{"user":"root","password":"exampleRoot","secure":"explicit"}}'

Response

{
  "id": 400,
  "organizationId": 1,
  "customerId": 2,
  "name": "FTP Availability",
  "hostname": "claas.sh",
  "port": 21,
  "status": "active",
  "checkInterval": 5,
  "timeoutSeconds": 30,
  "allowedCheckCountryCodes": null,
  "notificationPhoneNumber": null,
  "notificationEmail": null,
  "lastCheckedAt": null,
  "createdAt": "2026-02-25T10:00:00.000Z",
  "updatedAt": "2026-02-25T10:00:00.000Z",
  "config": {
    "user": "root",
    "password": "exampleRoot",
    "secure": "explicit"
  },
  "ftpConfig": {
    "user": "root",
    "password": "exampleRoot",
    "secure": "explicit"
  }
}

Common Errors

  • 400 Invalid Customer identifier if customerId is neither a valid UUID nor a legacy numeric ID
  • 400 hostname must be a valid hostname (no protocol, no path) on invalid hostnames
  • 401 Unauthorized if you are not authenticated
  • 403 Forbidden if you do not have access or are not allowed to create monitors (e.g. read-only or global supporter)
  • 404 Customer not found if the customerId does not exist
  • 403 targetHostMonitorLimitReached: the organization already has 100 monitors for this target host (see Limit per target host); allowDuplicate: true does not lift the limit
  • 403 targetHostPlatformLimitReached: the host already has 300 monitors across all Uptimeify customers (see Limit per target host)
  • 409 monitorAlreadyExists: this customer already has such a monitor (see Duplicates); allowDuplicate: true creates it anyway

On this page