# HTTP request configuration

Website/HTTPS (`http`) and API (`api`) monitors let you shape the exact request that is sent and decide what
counts as a good answer. By default a check succeeds when every stage succeeds: DNS resolves the host, the TCP
connection is established, the TLS handshake completes (for https), and the server answers with an HTTP status
below 400. The settings below live in the **Request Configuration** and **Response Validation** groups of the
monitor editor.

## Settings reference

| Setting (app label) | API field (`settings.*`) | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| **HTTP Method** | `method` | `H` (HEAD), `G` (GET), `P` (POST), `U` (PUT), `D` (DELETE), `A` (PATCH) | `G` (GET) | None | HEAD fetches headers only (fastest); GET downloads the page and is required for keyword checks; POST/PUT/PATCH also send a body. |
| **Request body** (**Plain text** or **Key-value**, as form-urlencoded or JSON) | `body` | Text, up to 2047 characters | Empty | None | Sent with POST, PUT and PATCH. Key-value mode composes the body and sets the matching `Content-Type` header. |
| - (API only, legacy) | `postParameters` | Form-encoded text, up to 2047 characters | Empty | None | Older form-parameter field; prefer `body`. |
| **HTTP Headers** (**Add Header**) | `headers` | Array of `{ "name", "value" }`; all names and values together up to 1023 characters | None | None | Extra request headers; they override the defaults below. `Connection`, `Content-Length` and `Date` are dropped. |
| **Request authentication** (**Username**, **Password**) | `username`, `password`, `authSchema` | Text up to 255 each; `authSchema`: `Basic` | Off | None | Answers the server's authentication challenge (Basic, Digest, NTLM, Kerberos, Negotiate). With `authSchema: "Basic"` (API) the Basic header is sent on the first request without waiting for a challenge. |
| **Follow redirects** / **Immediate response** / **Redirect is error** | `followRedirect`, `errorOnRedirect` | Booleans | Follow redirects (`followRedirect: true`) | None | Follow 3xx to the final page, judge the redirect response itself, or treat any redirect as a failure. |
| **Max redirects to follow** | `maxRedirects` | 1-20 | 20 | None | How many hops to follow before giving up. |
| **Content check keywords** | `keywords` | Comma-separated text, up to 255 characters in total | None | Keyword monitoring can be excluded by plan | Words searched for in the downloaded body (GET only). |
| **Successful content check condition** | `keywordMode` | `PresentAny`, `PresentAll`, `ReverseAny`, `ReverseAll`, `ReverseWithResult` | `PresentAny` | - | How the keywords decide pass or fail (table below). |
| **Ignore HTTP Errors** | `ignoredStatuses` | Up to 20 status codes, 100-599 | None | None | These statuses count as success (for example `401` on an endpoint that must require login). |
| **Error on these HTTP statuses** | `errorStatuses` | Up to 20 status codes, 100-599 | None | None | These statuses count as failure even though they are normally fine. |
| **Max response size** | `maxSize` | Bytes | 1 MB | - | See [Timeouts and response size](/monitors/advanced/response-limits/). |
| **DNS Server Selection** | `publicDns`, `dns` | **Default DNS servers at locations** / **Public DNS servers of location's country** (`publicDns`) / **Manually defined DNS servers** (`dns`, up to 4 IPs) | Default DNS servers at locations | Public and custom DNS are plan features | Which resolvers the checkpoint uses for your host. |
| **Excluded public DNS server IPs** | `expectedDns` | Up to 10 IPs | None | - | Public resolvers to skip when resolving through the public DNS pool. |
| **Expected IPs Validation** | `expectedIps` | Up to 10 IPv4/IPv6 addresses (or **Resolve IPs automatically**) | Off | None | Fails the check when the host resolves to any other address - catches DNS hijacking or a wrong record. |
| **Disable DNS cache** | `dnsNoCache` | Boolean | Off | None | Resolves the host fresh on every check instead of reusing the checkpoint's cached answer. |
| **TLS Handshake** switches | `requireValidChain`, `requireStrongTls`, `blockWeakCiphers`, `checkRevocation` | Booleans | Off | Plan feature | See [TLS handshake policy](/monitors/advanced/tls-policy/). |
| Assertion mode | `assertMode`, `asserts`, `assertsSource` | See [Assertions](/monitors/advanced/assertions/) | Off | Rule count per plan | Replaces keywords and status rules with a rule list. |

**Default request headers.** When you do not set them, the checkpoint sends `User-Agent: Mozilla/5.0 (compatible;
HostTracker/2.0; +https://www.host-tracker.com/)`, `Accept: */*`, `Accept-Language: en-US,en;q=0.9`, and a
`Referer` pointing to the monitor's results page on host-tracker.com. A header you add with the same name
replaces the default.

**Bearer tokens and API keys.** The authentication fields only answer a challenge. To send a token up front, add
it as a header, for example `Authorization: Bearer ...` or `X-Api-Key: ...`.

### Keyword conditions

| App option | `keywordMode` | The check passes when |
|---|---|---|
| **ANY keyword must be present** | `PresentAny` | at least one keyword is found |
| **ALL keywords must be present** | `PresentAll` | every keyword is found |
| **ANY keyword must be absent** | `ReverseAny` | none of the keywords is found; the check fails as soon as any one of them appears (the right choice for catching an error message inside a 200 page) |
| **ALL keywords must be absent** | `ReverseAll` | at least one keyword is missing; the check fails only when every keyword is found |
| **ALL keywords absent (fail shows location)** | `ReverseWithResult` | none is found; a failure reports the matched text |

:::caution[The two "absent" labels read the other way round]
With several keywords, **ANY keyword must be absent** actually fails when any keyword is present, and **ALL
keywords must be absent** fails only when all of them are present. The table above describes what the check does.
With a single keyword both options behave the same.
:::

## Set it up in the app

1. On **Sites**, open the Website/HTTPS or API monitor.
2. **Request Configuration**: pick the **HTTP Method**, fill the **Request body** (POST/PUT/PATCH), add **HTTP
   Headers**, switch on **Request authentication** if the site asks for a login, choose the redirect behaviour, and
   set the DNS options.
3. **Response Validation**: add **Content check keywords** and the **Successful content check condition**, list
   statuses under **Ignore HTTP Errors** or **Error on these HTTP statuses**, set **Max response size**, the **TLS
   Handshake** switches, and **Expected IPs Validation**.
4. **Save**.

## Do it with the API or MCP

```bash
# POST a JSON body with an API key, require "status":"ok" in the answer, accept 202 (scope monitor:write)
curl -X PATCH "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "settings": {
        "method": "P",
        "body": "{\"ping\":true}",
        "headers": [ { "name": "Content-Type", "value": "application/json" },
                     { "name": "X-Api-Key", "value": "secret" } ],
        "keywords": "\"status\":\"ok\"",
        "keywordMode": "PresentAll",
        "ignoredStatuses": [202]
      } }'
```

`settings` merges into what the monitor already has; send `null` for a member to clear it. The full per-type
schema is at `GET /monitor/type/http` (and `/monitor/type/api`). MCP: **`create_monitor`** / **`update_monitor`**
with `settingsJson` holding the same object.

## Limits and gotchas

- Keyword checks need GET: HEAD never downloads a body.
- **Redirect is error** is unavailable while assertion mode is on, and assertion mode refuses `keywords`,
  `keywordMode`, `ignoredStatuses`, `errorStatuses`, `errorOnRedirect` and `preset`.
- The Russian BL preset (`"preset": "bl:ru"`) builds the whole settings object itself: any other setting sent with
  it, or sent to a monitor created from it, is refused (`422 invalid_settings`).
- Passwords are stored and copied with the monitor. The account owner and subaccounts with edit rights can read
  them back; view-only subaccounts see only that one is set.
- Public DNS, custom DNS and the TLS switches are refused with `403 package_limit` when your plan does not include
  them; a value already saved keeps working.

## Related

- [Assertions and validation rules](/monitors/advanced/assertions/)
- [TLS handshake policy](/monitors/advanced/tls-policy/)
- [Timeouts and response size](/monitors/advanced/response-limits/)
- [Website / HTTPS monitor](/monitors/types/http/)