Skip to Content
Uptimeify Docs

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

FeldTypPflichtStandardBeschreibung
customerIdnumber|stringJa-Public ID des Kunden (bevorzugt) oder die alte numerische ID
namestringJa-Anzeigename, 1 bis 255 Zeichen
urlstringJa*-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).
monitoringTypestringNeincombinedcombined, http_status, ssl_check, playwright, heartbeat, dns
statusstringNeinactiveactive, inactive, maintenance (paused wird angenommen und auf inactive abgebildet)
checkIntervalnumberNein30Prü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.
timeoutSecondsnumberNein30Zeitlimit der Anfrage in Sekunden (1 bis 60)
expectedStatusCodesstringNein200,301,302Erwartete HTTP-Statuscodes, durch Komma getrennt. Nur Ziffern, Kommata und Leerzeichen.
allowedCheckCountryCodesstring[]|nullNeinVorgabe der OrganisationZweibuchstabige Ländercodes, die die Prüfstandorte einschränken
searchTermstring|nullNeinnullSchlüsselwort, nach dem im Antwortkörper gesucht wird (höchstens 255 Zeichen)
customFieldsobject|nullNeinnullEigene Feldwerte als Schlüssel-Wert-Paare
allowPaidQuotaUpgradebooleanNeinfalseZustimmung 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.
managementTypestringNeinmanagedOwnership-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

FeldTypPflichtStandardBeschreibung
authModestringNeinnonenone, authorization_header, basic
authorizationHeaderstring|nullNeinnullPflicht, wenn authMode auf authorization_header steht (1 bis 4096 Zeichen). Verschlüsselt gespeichert.
basicAuthUsernamestring|nullNeinnullPflicht, wenn authMode auf basic steht (1 bis 255 Zeichen)
basicAuthPasswordstring|nullNeinnullPflicht, wenn authMode auf basic steht (1 bis 4096 Zeichen). Verschlüsselt gespeichert.

HTTP-Anfrage konfigurieren

FeldTypPflichtStandardBeschreibung
httpMethodstringNeinGETGET, QUERY, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
customHeadersobject|nullNeinnullEigene HTTP-Header als Schlüssel-Wert-Paare. Schlüssel 1 bis 100 Zeichen, Werte höchstens 8192 Zeichen. Verschlüsselt gespeichert.
requestBodystring|nullNeinnullAnfragekörper, höchstens 100 KB. Wird bei jeder Methode außer GET und HEAD mitgesendet. Verschlüsselt gespeichert.
followRedirectsbooleanNeintrueOb Weiterleitungen verfolgt werden
cookieHandlingstringNeinnonenone 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

FeldTypPflichtStandardBeschreibung
connectHoststring|nullNeinnullDie 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).
connectPortnumber|nullNeinnullPort für connectHost (1 bis 65535). Fällt zurück auf einen in connectHost selbst enthaltenen Port, sonst auf den Port der URL.
connectTlsInsecurebooleanNeinfalseSchaltet 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)

FeldTypPflichtStandardBeschreibung
mtlsEnabledbooleanNeinfalseGegenseitige TLS-Authentifizierung einschalten
mtlsClientCertstring|nullNeinnullPflicht, wenn mtlsEnabled true ist (1 bis 100000 Zeichen). Verschlüsselt gespeichert.
mtlsClientKeystring|nullNeinnullPflicht, wenn mtlsEnabled true ist (1 bis 100000 Zeichen). Verschlüsselt gespeichert.

Playwright-Monitoring

FeldTypPflichtStandardBeschreibung
playwrightScriptstring|nullNein*nullPflicht, wenn monitoringType auf playwright steht (1 bis 100000 Zeichen)
playwrightEnvobject|nullNeinUmgebungsvariablen (höchstens 50; Schlüssel 1 bis 64 Zeichen und nach dem Muster ^[A-Z_][A-Z0-9_]*$, Werte höchstens 2000 Zeichen)
playwrightDevicestring|nullNeinnullVoreinstellung für die Geräteemulation (1 bis 100 Zeichen)
playwrightViewportWidthnumber|nullNeinnullBreite des Sichtfensters (1 bis 3840). Nur zusammen mit playwrightViewportHeight.
playwrightViewportHeightnumber|nullNeinnullHöhe des Sichtfensters (1 bis 3840). Nur zusammen mit playwrightViewportWidth.
playwrightRetriesnumber|nullNein0Anzahl der Wiederholungen (0 bis 5)
playwrightTimeoutMsnumber|nullNein30000Zeitlimit in Millisekunden (1000 bis 180000)

Erwartete Antwort prüfen

FeldTypPflichtStandardBeschreibung
checkExpectedResponseEnabledbooleanNeinfalsePrüfung des Antwortkörpers einschalten
expectedResponseMatchTypestring|nullNeincontainscontains, equals, json_path_equals
expectedResponseValuestring|nullNeinnullPflicht, wenn checkExpectedResponseEnabled true ist (höchstens 10000 Zeichen)
expectedResponseJsonPathstring|nullNeinnullPflicht, wenn expectedResponseMatchType auf json_path_equals steht (höchstens 500 Zeichen)

Prüfungen ein- und ausschalten

FeldTypPflichtStandardBeschreibung
checkSslEnabledbooleanNeintrueZertifikatsprüfung (bei Playwright abgeschaltet)
checkHttpsRedirectEnabledbooleanNeintruePrüfung der HTTPS-Weiterleitung (bei Playwright abgeschaltet)
checkStatusEnabledbooleanNeintruePrüfung des HTTP-Status (bei Playwright abgeschaltet)
checkSizeEnabledbooleanNeinfalsePrüfung der Antwortgröße (bei Playwright abgeschaltet). true ohne minPageSize oder maxPageSize antwortet 400 checkRequiresValue, denn ohne Grenze misst sie nichts.
checkResponseTimeEnabledbooleanNeintruePrüfung der Antwortzeit (bei Playwright abgeschaltet)
checkKeywordEnabledbooleanNeinfalseSuche 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

FeldTypPflichtStandardBeschreibung
sslNoticeDaysnumberNein7Tage vor Ablauf des Zertifikats für den Hinweis (1 bis 365)
sslErrorDaysnumberNein0Tage vor Ablauf des Zertifikats für den Fehler (0 bis 365, muss ≤ sslNoticeDays sein)
checkDomainExpiryEnabledbooleanNeintruePrüfung des Domain-Ablaufs (bei Playwright abgeschaltet)
domainExpiryNoticeDaysnumberNein30Tage vor Ablauf der Domain für den Hinweis (1 bis 365)
domainExpiryErrorDaysnumberNein7Tage vor Ablauf der Domain für den Fehler (0 bis 365, muss ≤ domainExpiryNoticeDays sein)

Grenzen der Seitengröße

FeldTypPflichtStandardBeschreibung
minPageSizenumber|nullNeinnullKleinste erwartete Seitengröße in Bytes (≥ 0, muss ≤ maxPageSize sein; bei Playwright abgeschaltet)
maxPageSizenumber|nullNeinnullGrößte erwartete Seitengröße in Bytes (≥ 0; bei Playwright abgeschaltet)

DNS-Monitoring

FeldTypPflichtStandardBeschreibung
dnsConfigobjectNeinKonfiguration der DNS-Abfrage (nur bei monitoringType: dns)

Heartbeat

FeldTypPflichtStandardBeschreibung
heartbeatTokenstring|nullNeinwird erzeugtEigenes Heartbeat-Token (höchstens 255 Zeichen)
heartbeatGracePeriodMinutesnumberNein5Karenzzeit in Minuten (1 bis 10080, also höchstens eine Woche)
expectedStatestringNeinupup: 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, Standard false): 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 bist
  • 403 Forbidden, wenn du für diese Organisation oder diesen Kunden keine Websites anlegen darfst
  • 403 Forbidden (selfServiceNotAllowed), wenn ein kunden-gescopter Aufrufer einen Monitor anlegt, das aufgelöste allowSelfService des Kunden aber false ist
  • 403 Forbidden (selfServiceQuotaReached), wenn die Zahl der Self-Service-Monitore des Kunden über alle Monitor-Typen hinweg maxSelfServiceUrls bereits erreicht
  • 403 Forbidden (checkNotInPackage), wenn ein ausdrückliches true eine Prüfung anschaltet, die das Paket des Kunden verbietet (data.check nennt sie)
  • 400 Bad Request (checkRequiresValue), wenn checkKeywordEnabled: true ohne nicht-leeren searchTerm kommt oder checkSizeEnabled: true ohne minPageSize bzw. maxPageSize (data.check, data.field)
  • 404 Customer not found, wenn sich customerId keinem bestehenden Kunden zuordnen lässt
  • 400 Bad Request (connectHostInvalid), wenn connectHost kein gültiger Host ist oder Protokoll bzw. Pfad enthält
  • 400 Bad Request (connectHostNotPublic), wenn connectHost auf eine private, Loopback-, Link-Local- oder sonst gesperrte Adresse auflöst
  • 400 Bad Request (connectTlsInsecureWithoutHost), wenn connectTlsInsecure ohne connectHost gesendet wird
  • 400 Bad Request (expectedStateNotSupported), wenn expectedState: "down" für einen Monitor kommt, der kein heartbeat-Monitor ist
  • 403 Forbidden mit data.code paidQuotaUpgradeNotAuthorized, wenn der Aufruf aus einer Agentenverbindung (MCP) kommt, die Organisation an ihrer Monitorgrenze steht und selbst hochstuft, und allowPaidQuotaUpgrade nicht auf true steht. 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 mit allowPaidQuotaUpgrade: true, sobald ein Mensch der höheren Rechnung zugestimmt hat, oder gib vorher einen Monitor frei.
  • 403 targetHostMonitorLimitReached: die Organisation hat schon 100 Monitore auf diesen Ziel-Host (siehe Grenze je Ziel-Host); allowDuplicate: true hebt die Grenze nicht auf
  • 403 targetHostPlatformLimitReached: auf den Host zeigen über alle Uptimeify-Kunden schon 300 Monitore (siehe Grenze je Ziel-Host)
  • 409 monitorAlreadyExists: dieser Kunde hat schon so einen Monitor (siehe Duplikate); allowDuplicate: true legt ihn trotzdem an

Auf dieser Seite