# Create monitor Returns a newly created monitor or validation errors. [endpoint] base_url = "https://uptime.betterstack.com" path = "/api/v2/monitors" method = "POST" [[body_param]] name = "team_name" description = "Required if using [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team which should own the resource" required = false type = "string" [[body_param]] name = "monitor_type" description = ''' Valid values:
`status` — We will check your website for a 2XX HTTP status code.
`expected_status_code` — We will check if your website returned one of the values in `expected_status_codes`.
`keyword` — We will check if your website contains the `required_keyword`.
`keyword_absence` — We will check if your website doesn't contain the `required_keyword`.
`ping` — We will ping your host specified in the `url` parameter.
`tcp` — We will test a TCP port at your host specified in the url parameter (`port` is required).
`udp` — We will test a UDP port at your host specified in the url parameter (`port` and `required_keyword` are required).
`smtp` — We will check for a SMTP server at the host specified in the url parameter (`port` is required, and can be one of `25`, `465`, `587`, or a combination of those ports separated by a comma).
`pop` — We will check for a POP3 server at the host specified in the `url` parameter (`port` is required, and can be `110`, `995`, or both).
`imap` — We will check for an IMAP server at the host specified in the url parameter (`port` is required, and can be 143, 993, or both).
`dns` — We will check for a DNS server at the host specified in the url parameter (`request_body` is required, and should contain the domain to query the DNS server with).
`playwright` — We will run the scenario defined by `playwright_script`, identified in the UI by `scenario_name`. ''' required = false type = "string" [[body_param]] name = "url" description = "The URL of your website or the host you want to ping. See `monitor_type` below." required = false type = "string" [[body_param]] name = "pronounceable_name" description = "The name of the monitor" required = false type = "string" [[body_param]] name = "email" description = "Send email alerts" required = false type = "boolean" [[body_param]] name = "sms" description = "Send SMS alerts" required = false type = "boolean" [[body_param]] name = "call" description = "Phone call alerts" required = false type = "boolean" [[body_param]] name = "critical_alert" description = "Should we send a critical push notification that ignores the mute switch and Do not Disturb mode?" required = false type = "boolean" [[body_param]] name = "critical_alert" description = "Should we send a critical alert to the on-call person?" required = false type = "boolean" [[body_param]] name = "check_frequency" description = "Check frequency (in seconds)" required = false type = "integer (30)" [[body_param]] name = "request_headers" description = "The request headers that will be send with the check" required = false type = "array of objects" [[body_param]] name = "expected_status_codes" description = "An array of status codes you expect to receive from your website. These status codes are considered only if the `monitor_type` is `expected_status_code`." required = false type = "array of integers" [[body_param]] name = "domain_expiration" description = "How many days before the domain expires do you want to be alerted? Valid values are 1, 2, 3, 7, 14, 30, and 60." required = false type = "integer" [[body_param]] name = "ssl_expiration" description = "How many days before the SSL certificate expires do you want to be alerted? Valid values are 1, 2, 3, 7, 14, 30, and 60." required = false type = "integer" [[body_param]] name = "policy_id" description = "Set the escalation policy for the monitor." required = false type = "string" [[body_param]] name = "expiration_policy_id" description = "Set the expiration escalation policy for the monitor. It is used for SSL certificate and domain expiration checks. When set to `null`, an e-mail is sent to the entire team." required = false type = "integer" [[body_param]] name = "follow_redirects" description = "Should we automatically follow redirects when sending the HTTP request?" required = false type = "boolean" [[body_param]] name = "required_keyword" description = "Required if monitor_type is set to keyword or udp. We will create a new incident if this keyword is missing on your page." required = false type = "string" [[body_param]] name = "team_wait" description = "How long to wait before escalating the incident alert to the team. Leave blank to disable escalating to the entire team. In seconds." required = false type = "integer" [[body_param]] name = "paused" description = "Set to true to pause monitoring — we won't notify you about downtime. Set to false to resume monitoring." required = false type = "boolean" [[body_param]] name = "port" description = "Required if `monitor_type` is set to `tcp`, `udp`, `smtp`, `pop`, or `imap`. `tcp` and `udp` monitors accept any ports, while smtp, pop, and imap accept only the specified ports corresponding with their servers (e.g. `25`,`465`,`587` for `smtp`)." required = false type = "string" [[body_param]] name = "regions" description = "An array of regions to set. Allowed values are `['us', 'eu', 'as', 'au']` or any subset of these regions." required = false type = "array of strings" [[body_param]] name = "monitor_group_id" description = "Set this attribute if you want to add this monitor to a monitor group." required = false type = "string" [[body_param]] name = "recovery_period" description = "How long the monitor must be up to automatically mark an incident as resolved after being down. In seconds." required = false type = "integer" [[body_param]] name = "verify_ssl" description = "Should we verify SSL certificate validity?" required = false type = "boolean" [[body_param]] name = "confirmation_period" description = "How long should we wait after observing a failure before we start a new incident? In seconds." required = false type = "integer" [[body_param]] name = "http_method" description = "HTTP Method used to make a request. Valid options: GET, HEAD, POST, PUT, PATCH" required = false type = "string" [[body_param]] name = "request_timeout" description = ''' How long to wait before timing out the request?

When `monitor_type` is set to `playwright`, this determines the Playwright scenario timeout instead. In seconds. Valid options: 15, 30, 45, 60, 120, 180, 240, 300, 360, 480, 600, 900. ''' required = false type = "integer" [[body_param]] name = "request_body" description = "Request body for POST, PUT, PATCH requests. Required if `monitor_type` is set to `dns` (domain to query the DNS server with)." required = false type = "string" [[body_param]] name = "auth_username" description = "Basic HTTP authentication username to include with the request." required = false type = "string" [[body_param]] name = "auth_password" description = "Basic HTTP authentication password to include with the request." required = false type = "string" [[body_param]] name = "maintenance_days" description = "An array of maintenance days to set. If a maintenance window is overnight both affected days should be set. Allowed values are `['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']` or any subset of these days." required = false type = "array of strings" [[body_param]] name = "maintenance_from" description = "Start of the maintenance window each day. We won't check your website during this window. Example: '01:00:00'" required = false type = "string" [[body_param]] name = "maintenance_to" description = "End of the maintenance window each day. Example: '03:00:00'" required = false type = "string" [[body_param]] name = "maintenance_timezone" description = "The timezone to use for the maintenance window each day. Defaults to UTC. The accepted values can be found in the Rails TimeZone documentation. https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html" required = false type = "string" [[body_param]] name = "remember_cookies" description = "Do you want to keep cookies when redirecting?" required = false type = "boolean" [[body_param]] name = "playwright_script" description = "For Playwright monitors, the JavaScript source code of the scenario." required = false type = "string" [[body_param]] name = "scenario_name" description = "For Playwright monitors, the scenario name identifying the monitor in the UI." required = false type = "string" [[body_param]] name = "environment_variables" description = "For Playwright monitors, the environment variables that can be used in the scenario. Example: `{ \"PASSWORD\": \"passw0rd\" }`." required = false type = "object" [[header]] name = "Authorization" description = "Bearer `$TOKEN`" required = true type = "string" [[header]] name = "Content-Type" description = "application/json" required = false type = "string" [/endpoint] [responses] [[response]] status = 201 description = '''Returns newly created monitor''' body = '''{ "data": { "id": "238", "type": "endpoint", "attributes": { "url": "https://uptime.betterstack.com", "pronounceable_name": "Uptime homepage", "monitor_type": "keyword", "monitor_group_id": "12345", "last_checked_at": "2020-09-01T14:17:46.000Z", "status": "up", "policy_id": null, "expiration_policy_id": null, "team_name": "Test team", "required_keyword": "We call you", "verify_ssl": true, "check_frequency": 30, "call": true, "sms": true, "email": true, "team_wait": null, "http_method": "get", "request_timeout": 15, "recovery_period": 0, "request_body": "", "paused_at": null, "created_at": "2020-02-18T13:38:16.586Z", "updated_at": "2020-09-08T13:10:20.202Z", "ssl_expiration": 7, "domain_expiration": 14, "regions": ["us", "eu", "as", "au"], "maintenance_days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"], "port": null, "expected_status_codes": [], "environment_variables": {} } } }''' [[response]] status = 422 description = '''Validation failed''' body = '''{ "errors": { "base": [ "URL is invalid." ] } }''' [/responses] #### Example cURL ```shell [label Example] curl --request POST \ --url https://uptime.betterstack.com/api/v2/monitors \ --header "Authorization: Bearer $TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "monitor_type": "status", "url": "https://facebook.com", "pronounceable_name": "Facebook homepage", "email": true, "sms": true, "call": true, "check_frequency": 30, "request_headers": [ { "name": "X-Custom-Header", "value": "custom header value" } ] }' ``` [info] #### Don't have your API token yet? Please, see [obtaining an API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/) #### Looking for the details of a specific parameter? Explore [the list of all monitor API parameters](https://betterstack.com/docs/uptime/api/monitors-api-response-params/) [/info]