Skip to Content
Uptimeify Docs
Websites

Create Website

Creates a new website monitor for a customer.

POST /api/websites

Example (cURL)

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

curl -X POST "$BASE_URL/api/websites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customerId": "059e1469-0f05-4c93-bd4d-89c45bb2afd9",
    "name": "New Landing Page",
    "url": "https://landing.deinkunde.com",
    "monitoringType": "combined",
    "checkInterval": 5
  }'

Example (cURL): Connect target

Measures the origin behind a WAF/CDN by connecting to a different host than the one in url, while the URL, path, Host header and TLS SNI stay the public hostname:

curl -X POST "$BASE_URL/api/websites" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"customerId":"...","name":"Shop (Origin)","url":"https://shop.example.com","connectHost":"origin.example.com","connectTlsInsecure":true}'

Request Body

Core fields

FieldTypeRequiredDefaultDescription
customerIdnumber|stringYes-Customer public ID (preferred) or legacy numeric ID
namestringYes-Display name (1-255 chars)
urlstringYes*-URL to monitor (max 2048 chars). Required for combined, http_status, ssl_check and dns; optional for heartbeat and playwright. HTTP monitors need a full URL including protocol; DNS monitors take a bare hostname (no protocol, no path).
monitoringTypestringNocombinedcombined, http_status, ssl_check, playwright, heartbeat, dns
statusstringNoactiveactive, inactive, maintenance (paused accepted, mapped to inactive)
checkIntervalnumberNo30Check interval in minutes. Actively scheduled monitors accept 1-1440 (24 hours); heartbeat monitors accept 1-43200 (30 days), because the value is the expected ping interval rather than a polling rate. The minimum your organization may set depends on the package.
timeoutSecondsnumberNo30Request timeout in seconds (1-60)
expectedStatusCodesstringNo200,301,302Comma-separated expected HTTP status codes. Digits, commas and spaces only.
allowedCheckCountryCodesstring[]|nullNoorg defaultArray of 2-letter country codes to restrict monitoring locations
searchTermstring|nullNonullKeyword to search for in response body (max 255 chars)
customFieldsobject|nullNonullCustom field values as key-value pairs
allowPaidQuotaUpgradebooleanNofalseConsent to a PAID quota upgrade. Only relevant when the organization is at its monitor quota AND has automatic quota upgrading switched on: an agent (MCP) call then needs this set to true, otherwise it is refused with paidQuotaUpgradeNotAuthorized and the message names the tier and the price. Any other caller is unaffected and the field is ignored - a person in the dashboard sees the price, a model does not. It is never stored and never part of duplicate detection.
managementTypestringNomanagedOwnership class: managed or self_service: see Managed vs. Self-Service. Only organization admins may choose it; customer-scoped creators always get self_service (requires allowSelfService and free quota).

Authentication

FieldTypeRequiredDefaultDescription
authModestringNononenone, authorization_header, basic
authorizationHeaderstring|nullNonullRequired when authMode is authorization_header (1-4096 chars). Encrypted at rest.
basicAuthUsernamestring|nullNonullRequired when authMode is basic (1-255 chars)
basicAuthPasswordstring|nullNonullRequired when authMode is basic (1-4096 chars). Encrypted at rest.

HTTP Request Configuration

FieldTypeRequiredDefaultDescription
httpMethodstringNoGETGET, QUERY, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
customHeadersobject|nullNonullCustom HTTP headers as key-value pairs. Keys: 1-100 chars, values: max 8192 chars. Encrypted at rest.
requestBodystring|nullNonullRequest body, max 100KB. Sent with every method except GET and HEAD. Encrypted at rest.
followRedirectsbooleanNotrueWhether to follow HTTP redirects
cookieHandlingstringNononenone or jar (maintain cookie jar across redirects)

Connect target (Ersatzziel)

FieldTypeRequiredDefaultDescription
connectHoststring|nullNonullConnects to this host/IP instead of the one in url, while the URL, path, Host header and TLS SNI stay unchanged - the semantics of curl --resolve. Host only, or host with port; IPv6 in brackets (e.g. [2001:db8::1]:8443); no protocol, no path. Useful for measuring the origin behind a WAF/CDN, or for running two monitors on the same URL that measure the edge and the origin separately. Private, loopback, link-local and otherwise blocked addresses are rejected (connectHostNotPublic).
connectPortnumber|nullNonullPort to use with connectHost (1-65535). Defaults to a port embedded in connectHost itself, then to the URL's own port.
connectTlsInsecurebooleanNofalseSkips certificate verification for the connection to connectHost. Only valid together with connectHost (connectTlsInsecureWithoutHost otherwise). SSL expiry and issuer are still read and reported.

Not available for playwright scenarios or heartbeat monitors: neither runs the HTTP/SSL check pipeline that connectHost plugs into, so the fields are accepted but have no effect on those monitoring types.

If checkHttpsRedirectEnabled is on, the "does http redirect to https" probe follows connectHost too and therefore measures the origin as well. Because that redirect is usually the WAF's job rather than the origin's, the monitor can rightly turn red for a redirect the public site still serves correctly.

mTLS (Mutual TLS)

FieldTypeRequiredDefaultDescription
mtlsEnabledbooleanNofalseEnable mutual TLS authentication
mtlsClientCertstring|nullNonullRequired when mtlsEnabled is true (1-100000 chars). Encrypted at rest.
mtlsClientKeystring|nullNonullRequired when mtlsEnabled is true (1-100000 chars). Encrypted at rest.

Playwright Monitoring

FieldTypeRequiredDefaultDescription
playwrightScriptstring|nullNo*nullRequired when monitoringType is playwright (1-100000 chars)
playwrightEnvobject|nullNoEnvironment variables (max 50, keys 1-64 chars and matching ^[A-Z_][A-Z0-9_]*$, values max 2000 chars)
playwrightDevicestring|nullNonullDevice emulation preset (1-100 chars)
playwrightViewportWidthnumber|nullNonullViewport width (1-3840). Must be set with playwrightViewportHeight.
playwrightViewportHeightnumber|nullNonullViewport height (1-3840). Must be set with playwrightViewportWidth.
playwrightRetriesnumber|nullNo0Number of retries (0-5)
playwrightTimeoutMsnumber|nullNo30000Timeout in milliseconds (1000-180000)

Expected Response Validation

FieldTypeRequiredDefaultDescription
checkExpectedResponseEnabledbooleanNofalseEnable response body validation
expectedResponseMatchTypestring|nullNocontainscontains, equals, json_path_equals
expectedResponseValuestring|nullNonullRequired when checkExpectedResponseEnabled is true (max 10000 chars)
expectedResponseJsonPathstring|nullNonullRequired when expectedResponseMatchType is json_path_equals (max 500 chars)

Check Configuration

FieldTypeRequiredDefaultDescription
checkSslEnabledbooleanNotrueEnable SSL certificate checks (disabled for Playwright)
checkHttpsRedirectEnabledbooleanNotrueCheck HTTPS redirect (disabled for Playwright)
checkStatusEnabledbooleanNotrueCheck HTTP status (disabled for Playwright)
checkSizeEnabledbooleanNofalseCheck response size (disabled for Playwright). true without minPageSize or maxPageSize answers 400 checkRequiresValue: without a bound the check measures nothing.
checkResponseTimeEnabledbooleanNotrueCheck response time (disabled for Playwright)
checkKeywordEnabledbooleanNofalseEnable keyword search (disabled for Playwright). true without a non-empty searchTerm answers 400 checkRequiresValue: without one the check measures nothing.

An omitted check field takes its default from your organization's package: a check the package forbids is then created as false without an error. An explicit true is rejected instead of being stored as false: 403 with data.code checkNotInPackage when the package forbids that check, and 400 with data.code checkRequiresValue when checkKeywordEnabled has no non-empty searchTerm (data.field: searchTerm) or checkSizeEnabled has neither minPageSize nor maxPageSize (data.field: minPageSize). data.check names the check; the package is checked first. false is always accepted.

SSL & Domain Thresholds

FieldTypeRequiredDefaultDescription
sslNoticeDaysnumberNo7Days before SSL expiry to trigger notice (1-365)
sslErrorDaysnumberNo0Days before SSL expiry to trigger error (0-365, must be ≤ sslNoticeDays)
checkDomainExpiryEnabledbooleanNotrueEnable domain expiry checks (disabled for Playwright)
domainExpiryNoticeDaysnumberNo30Days before domain expiry to trigger notice (1-365)
domainExpiryErrorDaysnumberNo7Days before domain expiry to trigger error (0-365, must be ≤ domainExpiryNoticeDays)

Page Size Limits

FieldTypeRequiredDefaultDescription
minPageSizenumber|nullNonullMinimum expected page size in bytes (≥ 0, must be ≤ maxPageSize; disabled for Playwright)
maxPageSizenumber|nullNonullMaximum expected page size in bytes (≥ 0; disabled for Playwright)

DNS Monitoring

FieldTypeRequiredDefaultDescription
dnsConfigobjectNoDNS query configuration (only for monitoringType: dns)

Heartbeat

FieldTypeRequiredDefaultDescription
heartbeatTokenstring|nullNoauto-generatedCustom heartbeat token (max 255 chars)
heartbeatGracePeriodMinutesnumberNo5Grace period in minutes (1-10080, max 1 week)
expectedStatestringNoupup: alert when pings stop. down: alert when a ping arrives (for jobs that only ping when something went wrong); every ping opens an incident, which resolves after interval + heartbeatGracePeriodMinutes without a ping. Other monitoring types accept only up (400 expectedStateNotSupported otherwise).

Duplicates

If this customer already has a monitor with the same url and monitoringType and the same connect target (connectHost, connectPort). Scheme and host case, the default port, a trailing slash and the #fragment do not count; path and query do. heartbeat and playwright monitors are never duplicates, 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. If a website has a connect target (connectHost), the connect target counts as its host. heartbeat monitors do not count. 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 target (url or connectHost). 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 }
}

Response

Returns the created website record. Encrypted fields (authorizationHeader, basicAuthPassword, customHeaders, requestBody, mtlsClientCert, mtlsClientKey) are never returned in API responses.

{
  "id": 103,
  "customerId": 1,
  "name": "New Landing Page",
  "url": "https://landing.deinkunde.com",
  "status": "active",
  "monitoringType": "combined",
  "checkInterval": 5,
  "httpMethod": "GET",
  "followRedirects": true,
  "cookieHandling": "none",
  "mtlsEnabled": false,
  "connectHost": null,
  "connectPort": null,
  "connectTlsInsecure": false,
  "expectedState": "up",
  "createdAt": "2026-02-26T12:05:00.000Z"
}

GET /api/websites/:id and GET /api/websites return connectHost, connectPort and connectTlsInsecure the same way.

Every website response carries expectedState: up or down for heartbeat monitors, always up for every other type.

Common errors

  • 401 Unauthorized when you are not logged in
  • 403 Forbidden when you cannot create websites for the organization/customer
  • 403 Forbidden (selfServiceNotAllowed) when a customer-scoped caller creates a monitor but the customer's resolved allowSelfService is false
  • 403 Forbidden (selfServiceQuotaReached) when the customer's total self-service monitors (across all monitor types) already meet maxSelfServiceUrls
  • 403 Forbidden (checkNotInPackage) when an explicit true switches on a check the customer's package forbids (data.check names it)
  • 400 Bad Request (checkRequiresValue) when checkKeywordEnabled: true comes without a non-empty searchTerm, or checkSizeEnabled: true without minPageSize or maxPageSize (data.check, data.field)
  • 404 Customer not found when customerId does not resolve to an existing customer
  • 400 Bad Request (connectHostInvalid) when connectHost is not a valid host, or carries a protocol or a path
  • 400 Bad Request (connectHostNotPublic) when connectHost resolves to a private, loopback, link-local or otherwise blocked address
  • 400 Bad Request (connectTlsInsecureWithoutHost) when connectTlsInsecure is sent without connectHost
  • 400 Bad Request (expectedStateNotSupported) when expectedState: "down" is sent for a monitor that is not a heartbeat monitor
  • 403 Forbidden with data.code paidQuotaUpgradeNotAuthorized when the call comes from an agent (MCP) connection, the organization is at its monitor quota with automatic upgrading switched on, and allowPaidQuotaUpgrade was not set to true. Creating the monitor would have moved the organization to the next, more expensive quota tier and billed the difference for the rest of the period; the message names that tier and its monthly price. Repeat the call with allowPaidQuotaUpgrade: true once a person has agreed to the higher bill, or free up a monitor first.
  • 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