monitoring.checks.create

Create an uptime check

POST /monitoring/api/checksIAM monitoring:CreateCheckChanges state

The check runs within a minute, then every intervalSeconds. A failed run is retried once after 3 s; failureThreshold failed runs in a row make it DOWN, two successful runs make it UP again, and both are mailed to notifyEmails and POSTed to webhookUrl. Unconfirmed runs are repeated after a minute. At most 50 checks per organization, and at most 6 requests a minute to one host across every check on Deutsche Cloud.

Request syntax

POST /monitoring/api/checks
{
  "name": "string",
  "type": "enum",
  "url": "string",
  "method": "enum",
  "expectedStatusMin": "number",
  "expectedStatusMax": "number",
  "keyword": "string",
  "keywordMode": "enum",
  "timeoutMs": "number",
  "intervalSeconds": "number",
  "followRedirects": "boolean",
  "verifyTls": "boolean",
  "failureThreshold": "number",
  "confirmations": "number",
  "alertOnRegional": "boolean",
  "notifyEmails": "array of string",
  "webhookUrl": "string"
}

Request body

  • nameRequired

    string

    Unique in the organization, up to 128 characters

  • typeOptional

    enum

    http: the status decides; keyword: the body must (not) contain a text too

    One of: http, keyword

  • urlRequired

    string

    http:// or https:// on a public address; any port except 25, 465 and 587

  • methodOptional

    enum

    GET by default; keyword checks use GET

    One of: GET, HEAD

  • expectedStatusMinOptional

    number

    Lowest status that counts as up (default 200)

    Constraints: integer

  • expectedStatusMaxOptional

    number

    Highest status that counts as up (default 399)

    Constraints: integer

  • keywordOptional

    string

    For keyword checks: the text looked for in the first 1 MiB

    May be null.

  • keywordModeOptional

    enum

    contains (default) or not_contains

    One of: contains, not_contains

    May be null.

  • timeoutMsOptional

    number

    1000–30000, default 10000

    Constraints: integer

  • intervalSecondsOptional

    number

    60, 120, 300 (default), 600, 900, 1800 or 3600

    Constraints: integer

  • followRedirectsOptional

    boolean

    Follow up to 5 redirects, each re-checked (default true)

  • verifyTlsOptional

    boolean

    Fail on an invalid certificate (default true)

  • failureThresholdOptional

    number

    Failed runs in a row before DOWN, 1–5 (default 2)

    Constraints: integer

  • confirmationsOptional

    number

    Locations that must fail in one run for it to count as failed, 1–3 (default 2); fewer failing is "regional"

    Constraints: integer

  • alertOnRegionalOptional

    boolean

    Treat one failing location as failed, as if confirmations were 1 (default false)

  • notifyEmailsOptional

    array of string

    Up to 10 addresses mailed on DOWN and on UP again

  • webhookUrlOptional

    string

    https URL on a public address, POSTed on DOWN and UP

    May be null.

Response

201 with the new check as get describes it, state pending. 409 when the name is taken, when the host is already requested 6 times a minute across the platform, or (code QuotaExceeded) past the organization’s quota monitoring.uptime-checks (50 by default, 10 on a trial; a quota can be raised); 400 when the fields disagree (a keyword on an http check, HEAD on a keyword check, min above max).

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow monitoring:CreateCheck on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud monitoring checks create --name example --url example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_monitoring_checks_create.