Website erstellen
Erstellt einen neuen Website-Monitor für einen Kunden.
POST /api/websites
Beispiel (cURL)
BASE_URL="https://uptimeify.io"
TOKEN="<dein-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": "Neue Landing Page",
"url": "https://landing.deinkunde.com",
"monitoringType": "combined",
"checkInterval": 5
}'Beispiel (cURL): Ersatzziel
Misst den Origin hinter einer WAF/CDN, indem die Verbindung zu einem anderen Host geht als in
url steht - URL, Pfad, Host-Header und TLS-SNI bleiben der öffentliche 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}'Anfrage (Request Body)
Kernfelder
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
customerId | number|string | Ja | - | Public ID des Kunden (bevorzugt) oder die alte numerische ID |
name | string | Ja | - | Anzeigename, 1 bis 255 Zeichen |
url | string | Ja* | - | Zu überwachende Adresse, höchstens 2048 Zeichen. Pflicht bei combined, http_status, ssl_check und dns; entfällt bei heartbeat und playwright. HTTP-Monitore brauchen die vollständige URL samt Protokoll, DNS-Monitore nur den Hostnamen (ohne Protokoll, ohne Pfad). |
monitoringType | string | Nein | combined | combined, http_status, ssl_check, playwright, heartbeat, dns |
status | string | Nein | active | active, inactive, maintenance (paused wird angenommen und auf inactive abgebildet) |
checkInterval | number | Nein | 30 | Prüfintervall in Minuten. Aktiv getaktete Monitore nehmen 1 bis 1440 (24 Stunden), heartbeat-Monitore 1 bis 43200 (30 Tage), dort ist der Wert das erwartete Ping-Intervall und keine Abfragefrequenz. Welchen Mindestwert deine Organisation setzen darf, hängt am Paket. |
timeoutSeconds | number | Nein | 30 | Zeitlimit der Anfrage in Sekunden (1 bis 60) |
expectedStatusCodes | string | Nein | 200,301,302 | Erwartete HTTP-Statuscodes, durch Komma getrennt. Nur Ziffern, Kommata und Leerzeichen. |
allowedCheckCountryCodes | string[]|null | Nein | Vorgabe der Organisation | Zweibuchstabige Ländercodes, die die Prüfstandorte einschränken |
searchTerm | string|null | Nein | null | Schlüsselwort, nach dem im Antwortkörper gesucht wird (höchstens 255 Zeichen) |
customFields | object|null | Nein | null | Eigene Feldwerte als Schlüssel-Wert-Paare |
allowPaidQuotaUpgrade | boolean | Nein | false | Zustimmung zu einer KOSTENPFLICHTIGEN Kontingent-Hochstufung. Zählt nur, wenn die Organisation an ihrer Monitorgrenze steht UND selbst hochstuft: ein Aufruf aus einer Agentenverbindung (MCP) braucht dann true, sonst wird er mit paidQuotaUpgradeNotAuthorized abgewiesen und die Meldung nennt Stufe und Preis. Jeder andere Aufrufer bleibt unberührt, das Feld wird ignoriert - ein Mensch im Dashboard sieht den Preis, ein Modell nicht. Es wird nie gespeichert und geht nicht in die Dublettenerkennung ein. |
managementType | string | Nein | managed | Ownership-Klasse: managed oder self_service, siehe Managed vs. Self-Service. Nur Organisations-Admins dürfen sie wählen; kunden-gescopte Ersteller erhalten immer self_service (erfordert allowSelfService und freies Kontingent). |
Authentifizierung
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
authMode | string | Nein | none | none, authorization_header, basic |
authorizationHeader | string|null | Nein | null | Pflicht, wenn authMode auf authorization_header steht (1 bis 4096 Zeichen). Verschlüsselt gespeichert. |
basicAuthUsername | string|null | Nein | null | Pflicht, wenn authMode auf basic steht (1 bis 255 Zeichen) |
basicAuthPassword | string|null | Nein | null | Pflicht, wenn authMode auf basic steht (1 bis 4096 Zeichen). Verschlüsselt gespeichert. |
HTTP-Anfrage konfigurieren
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
httpMethod | string | Nein | GET | GET, QUERY, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
customHeaders | object|null | Nein | null | Eigene HTTP-Header als Schlüssel-Wert-Paare. Schlüssel 1 bis 100 Zeichen, Werte höchstens 8192 Zeichen. Verschlüsselt gespeichert. |
requestBody | string|null | Nein | null | Anfragekörper, höchstens 100 KB. Wird bei jeder Methode außer GET und HEAD mitgesendet. Verschlüsselt gespeichert. |
followRedirects | boolean | Nein | true | Ob Weiterleitungen verfolgt werden |
cookieHandling | string | Nein | none | none oder jar, letzteres behält Cookies über Weiterleitungen hinweg |
QUERY ist sicher und idempotent wie GET, trägt aber einen Anfragekörper. Gedacht für die Fälle, in denen heute POST steht, obwohl nur gelesen wird: Suchen, Filter, GraphQL-artige Abfragen. Ein serverseitiges Regelwerk, das POST als schreibenden Zugriff behandelt, sieht die Prüfung damit nicht mehr als solchen.
Ersatzziel
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
connectHost | string|null | Nein | null | Die Verbindung geht an diesen Host/diese IP statt an den aus url, während URL, Pfad, Host-Header und TLS-SNI unverändert bleiben - die Semantik von curl --resolve. Nur Host, oder Host mit Port; IPv6 in eckigen Klammern (z. B. [2001:db8::1]:8443); kein Protokoll, kein Pfad. Nützlich, um den Origin hinter einer WAF/CDN zu messen, oder um mit zwei Monitoren auf derselben URL Edge und Origin getrennt zu überwachen. Private, Loopback-, Link-Local- und sonst gesperrte Adressen werden abgelehnt (connectHostNotPublic). |
connectPort | number|null | Nein | null | Port für connectHost (1 bis 65535). Fällt zurück auf einen in connectHost selbst enthaltenen Port, sonst auf den Port der URL. |
connectTlsInsecure | boolean | Nein | false | Schaltet die Zertifikatsprüfung für die Verbindung zu connectHost ab. Nur gültig zusammen mit connectHost (sonst connectTlsInsecureWithoutHost). Ablaufdatum und Aussteller des Zertifikats werden weiter gelesen und gemeldet. |
Nicht verfügbar für playwright-Szenarien und heartbeat-Monitore: beide durchlaufen nicht die HTTP/SSL-Prüfkette, in die connectHost eingreift - die Felder werden angenommen, wirken sich bei diesen Monitor-Arten aber nicht aus.
Ist checkHttpsRedirectEnabled eingeschaltet, folgt auch die Prüfung "leitet http auf https um" dem connectHost und misst damit ebenfalls den Origin. Weil diese Umleitung meist die WAF übernimmt und nicht der Origin, kann der Monitor dadurch zu Recht rot werden, obwohl die öffentliche Seite die Umleitung korrekt ausliefert.
mTLS (gegenseitiges TLS)
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
mtlsEnabled | boolean | Nein | false | Gegenseitige TLS-Authentifizierung einschalten |
mtlsClientCert | string|null | Nein | null | Pflicht, wenn mtlsEnabled true ist (1 bis 100000 Zeichen). Verschlüsselt gespeichert. |
mtlsClientKey | string|null | Nein | null | Pflicht, wenn mtlsEnabled true ist (1 bis 100000 Zeichen). Verschlüsselt gespeichert. |
Playwright-Monitoring
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
playwrightScript | string|null | Nein* | null | Pflicht, wenn monitoringType auf playwright steht (1 bis 100000 Zeichen) |
playwrightEnv | object|null | Nein | Umgebungsvariablen (höchstens 50; Schlüssel 1 bis 64 Zeichen und nach dem Muster ^[A-Z_][A-Z0-9_]*$, Werte höchstens 2000 Zeichen) | |
playwrightDevice | string|null | Nein | null | Voreinstellung für die Geräteemulation (1 bis 100 Zeichen) |
playwrightViewportWidth | number|null | Nein | null | Breite des Sichtfensters (1 bis 3840). Nur zusammen mit playwrightViewportHeight. |
playwrightViewportHeight | number|null | Nein | null | Höhe des Sichtfensters (1 bis 3840). Nur zusammen mit playwrightViewportWidth. |
playwrightRetries | number|null | Nein | 0 | Anzahl der Wiederholungen (0 bis 5) |
playwrightTimeoutMs | number|null | Nein | 30000 | Zeitlimit in Millisekunden (1000 bis 180000) |
Erwartete Antwort prüfen
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
checkExpectedResponseEnabled | boolean | Nein | false | Prüfung des Antwortkörpers einschalten |
expectedResponseMatchType | string|null | Nein | contains | contains, equals, json_path_equals |
expectedResponseValue | string|null | Nein | null | Pflicht, wenn checkExpectedResponseEnabled true ist (höchstens 10000 Zeichen) |
expectedResponseJsonPath | string|null | Nein | null | Pflicht, wenn expectedResponseMatchType auf json_path_equals steht (höchstens 500 Zeichen) |
Prüfungen ein- und ausschalten
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
checkSslEnabled | boolean | Nein | true | Zertifikatsprüfung (bei Playwright abgeschaltet) |
checkHttpsRedirectEnabled | boolean | Nein | true | Prüfung der HTTPS-Weiterleitung (bei Playwright abgeschaltet) |
checkStatusEnabled | boolean | Nein | true | Prüfung des HTTP-Status (bei Playwright abgeschaltet) |
checkSizeEnabled | boolean | Nein | false | Prüfung der Antwortgröße (bei Playwright abgeschaltet). true ohne minPageSize oder maxPageSize antwortet 400 checkRequiresValue, denn ohne Grenze misst sie nichts. |
checkResponseTimeEnabled | boolean | Nein | true | Prüfung der Antwortzeit (bei Playwright abgeschaltet) |
checkKeywordEnabled | boolean | Nein | false | Suche nach dem Schlüsselwort (bei Playwright abgeschaltet). true ohne nicht-leeren searchTerm antwortet 400 checkRequiresValue, denn ohne Suchbegriff misst sie nichts. |
Ein weggelassenes Prüf-Feld richtet seine Voreinstellung nach dem Paket der Organisation: eine vom Paket verbotene Prüfung entsteht dann ohne Fehler auf false. Ein ausdrückliches true wird dagegen abgewiesen, statt still als false gespeichert zu werden: 403 mit data.code checkNotInPackage, wenn das Paket diese Prüfung verbietet, und 400 mit data.code checkRequiresValue, wenn checkKeywordEnabled keinen nicht-leeren searchTerm hat (data.field: searchTerm) oder checkSizeEnabled weder minPageSize noch maxPageSize (data.field: minPageSize). data.check nennt die Prüfung; das Paket wird zuerst geprüft. false ist immer erlaubt.
Schwellen für Zertifikat und Domain
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
sslNoticeDays | number | Nein | 7 | Tage vor Ablauf des Zertifikats für den Hinweis (1 bis 365) |
sslErrorDays | number | Nein | 0 | Tage vor Ablauf des Zertifikats für den Fehler (0 bis 365, muss ≤ sslNoticeDays sein) |
checkDomainExpiryEnabled | boolean | Nein | true | Prüfung des Domain-Ablaufs (bei Playwright abgeschaltet) |
domainExpiryNoticeDays | number | Nein | 30 | Tage vor Ablauf der Domain für den Hinweis (1 bis 365) |
domainExpiryErrorDays | number | Nein | 7 | Tage vor Ablauf der Domain für den Fehler (0 bis 365, muss ≤ domainExpiryNoticeDays sein) |
Grenzen der Seitengröße
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
minPageSize | number|null | Nein | null | Kleinste erwartete Seitengröße in Bytes (≥ 0, muss ≤ maxPageSize sein; bei Playwright abgeschaltet) |
maxPageSize | number|null | Nein | null | Größte erwartete Seitengröße in Bytes (≥ 0; bei Playwright abgeschaltet) |
DNS-Monitoring
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
dnsConfig | object | Nein | Konfiguration der DNS-Abfrage (nur bei monitoringType: dns) |
Heartbeat
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
heartbeatToken | string|null | Nein | wird erzeugt | Eigenes Heartbeat-Token (höchstens 255 Zeichen) |
heartbeatGracePeriodMinutes | number | Nein | 5 | Karenzzeit in Minuten (1 bis 10080, also höchstens eine Woche) |
expectedState | string | Nein | up | up: Alarm, wenn die Pings ausbleiben. down: Alarm, wenn ein Ping ankommt (für Jobs, die sich nur im Fehlerfall melden); jeder Ping öffnet einen Vorfall, der sich nach Intervall + heartbeatGracePeriodMinutes ohne Ping schließt. Andere Monitor-Typen akzeptieren nur up (sonst 400 expectedStateNotSupported). |
Duplikate
Hat dieser Kunde schon einen Monitor mit dieselbe url, derselbe monitoringType und dasselbe Ersatzziel (connectHost, connectPort). Gross- und Kleinschreibung von Schema und Host, der Standardport, ein Schrägstrich am Ende und das #Fragment zählen nicht, Pfad und Query schon. heartbeat- und playwright-Monitore sind nie Duplikate, wird die Anfrage mit 409 und data.code monitorAlreadyExists abgewiesen. data.existingId und data.existingPublicId nennen den vorhandenen Monitor. Mit "allowDuplicate": true wird der zweite Monitor trotzdem angelegt (zum Beispiel mit anderem Intervall oder anderen Alarmwegen).
allowDuplicate(boolean, optional, Standardfalse): Monitor auch als Duplikat anlegen. Wird nicht gespeichert.
{
"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" }
}Grenze je Ziel-Host
Eine Organisation kann höchstens 100 Monitore auf denselben Ziel-Host haben, gezählt über alle Monitortypen zusammen (Websites mit HTTP, Keyword, DNS-Website und Playwright mit echter URL, dazu TCP, ICMP, DNS, SSH, SMTP, FTP und IMAP/POP). Die Grenze schützt davor, dass die Checkflotte als Lastgenerator gegen fremde Hosts missbraucht wird. Verglichen wird der exakte Hostname: Gross- und Kleinschreibung, Port, Pfad und ein Punkt am Ende zählen nicht, www.example.com und example.com sind aber verschiedene Hosts. Hat eine Website ein Ersatzziel (connectHost), zählt das Ersatzziel als Host. heartbeat-Monitore zählen nicht. Ist die Grenze erreicht, wird die Anfrage mit 403 und data.code targetHostMonitorLimitReached abgewiesen. data.host nennt den normalisierten Host, data.limit die Grenze. "allowDuplicate": true hebt die Grenze nicht auf. Dieselbe Prüfung läuft, wenn ein PATCH das Ziel ändert (url oder connectHost). Ein PATCH ohne Hostwechsel geht immer, vorhandene Monitore über der Grenze bleiben bestehen. Brauchst du eine höhere Grenze, wende dich an den Support. Unabhängig von deiner Organisation dürfen über alle Uptimeify-Kunden hinweg höchstens 300 Monitore auf denselben Host zeigen. Darüber wird die Anfrage mit 403 und data.code targetHostPlatformLimitReached abgewiesen; data.host und data.limit sind wie oben gesetzt, die Meldung verrät nicht, wie viele Monitore andere Organisationen haben.
{
"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 }
}Antwort (Response)
Gibt den angelegten Website-Datensatz zurück. Die verschlüsselt gespeicherten Felder (authorizationHeader, basicAuthPassword, customHeaders, requestBody, mtlsClientCert, mtlsClientKey) gibt die API grundsätzlich nicht heraus.
{
"id": 103,
"customerId": 1,
"name": "Neue 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 und GET /api/websites geben connectHost, connectPort und connectTlsInsecure genauso zurück.
Jede Website-Antwort enthält expectedState: up oder down bei heartbeat-Monitoren, bei allen anderen Typen immer up.
Häufige Fehler
401 Unauthorized, wenn du nicht angemeldet bist403 Forbidden, wenn du für diese Organisation oder diesen Kunden keine Websites anlegen darfst403 Forbidden(selfServiceNotAllowed), wenn ein kunden-gescopter Aufrufer einen Monitor anlegt, das aufgelösteallowSelfServicedes Kunden aber false ist403 Forbidden(selfServiceQuotaReached), wenn die Zahl der Self-Service-Monitore des Kunden über alle Monitor-Typen hinwegmaxSelfServiceUrlsbereits erreicht403 Forbidden(checkNotInPackage), wenn ein ausdrücklichestrueeine Prüfung anschaltet, die das Paket des Kunden verbietet (data.checknennt sie)400 Bad Request(checkRequiresValue), wenncheckKeywordEnabled: trueohne nicht-leerensearchTermkommt odercheckSizeEnabled: trueohneminPageSizebzw.maxPageSize(data.check,data.field)404 Customer not found, wenn sichcustomerIdkeinem bestehenden Kunden zuordnen lässt400 Bad Request(connectHostInvalid), wennconnectHostkein gültiger Host ist oder Protokoll bzw. Pfad enthält400 Bad Request(connectHostNotPublic), wennconnectHostauf eine private, Loopback-, Link-Local- oder sonst gesperrte Adresse auflöst400 Bad Request(connectTlsInsecureWithoutHost), wennconnectTlsInsecureohneconnectHostgesendet wird400 Bad Request(expectedStateNotSupported), wennexpectedState: "down"für einen Monitor kommt, der keinheartbeat-Monitor ist403 Forbiddenmitdata.codepaidQuotaUpgradeNotAuthorized, wenn der Aufruf aus einer Agentenverbindung (MCP) kommt, die Organisation an ihrer Monitorgrenze steht und selbst hochstuft, undallowPaidQuotaUpgradenicht auftruesteht. Der Monitor hätte die Organisation auf die nächste, teurere Stufe gehoben und die Differenz für den Rest des Zeitraums abgerechnet; die Meldung nennt Stufe und Monatspreis. Wiederhole den Aufruf mitallowPaidQuotaUpgrade: true, sobald ein Mensch der höheren Rechnung zugestimmt hat, oder gib vorher einen Monitor frei.403targetHostMonitorLimitReached: die Organisation hat schon 100 Monitore auf diesen Ziel-Host (siehe Grenze je Ziel-Host);allowDuplicate: truehebt die Grenze nicht auf403targetHostPlatformLimitReached: auf den Host zeigen über alle Uptimeify-Kunden schon 300 Monitore (siehe Grenze je Ziel-Host)409monitorAlreadyExists: dieser Kunde hat schon so einen Monitor (siehe Duplikate);allowDuplicate: truelegt ihn trotzdem an