Skip to Content
API ReferenceCreate Check

Create Check

Create a new monitoring check.

Required scope: checks:write

Endpoint

POST /v1/public/checks

Headers

HeaderRequiredDescription
X-Api-KeyYesYour API key
Content-TypeYesMust be application/json
Idempotency-KeyYesUnique key to prevent duplicate creation: 1 to 256 letters, digits, hyphens or underscores

Request Body

FieldTypeRequiredDescription
urlstringYesThe URL, host or domain to monitor. Not required for heartbeat checks: exit1 generates a unique ping URL automatically
namestringNoDisplay name (max 200 characters, defaults to the URL)
folderstringNoFolder path such as Clients/Acme (at most 10 levels, 48 characters per folder name). Required for a key restricted to folders: it must be one of the key’s folders or a subfolder
typestringNoCheck type: website, rest_endpoint, redirect, ping, tcp, udp, websocket, dns, heartbeat or domain (default: website). Unrecognized values fall back to website. dns requires a paid plan. domain tracks domain expiry only (no uptime probe), takes a bare domain such as example.com as url, and requires Nano or Pro
checkFrequencynumberNoMinutes between checks (default: 5, subject to plan limits)
checkRegionOverridestringNoRegion to run the check from: vps-eu-1 (Frankfurt) or vps-us-1 (Boston). Only honored on plans with region choice (Nano and Pro). On other plans the check always runs from vps-eu-1
httpMethodstringNoHTTP method for website, rest_endpoint and redirect checks: GET, POST, PUT, PATCH, DELETE or HEAD (default: GET)
expectedStatusCodesnumber[]NoStatus codes that count as up, integers from 100 to 599. Defaults depend on type (see below)
requestHeadersobjectNoCustom request headers as string key-value pairs (max 20 entries, values max 2048 characters). Host, Authorization, Cookie, Set-Cookie, X-Forwarded-For, X-Real-IP, Proxy-Authorization, Transfer-Encoding and Content-Length are rejected
requestBodystringNoRequest body (max 65,536 characters). Must be valid JSON for rest_endpoint checks using POST, PUT or PATCH
responseValidationobjectNoResponse validation rules (see below)
redirectValidationobjectNoFor redirect checks: { "expectedTarget": "https://...", "matchMode": "contains" }. matchMode is contains (default) or exact
maxRedirectsintegerNoMaximum redirects to follow (0 to 10)
cacheControlNoCachebooleanNoSend Cache-Control: no-cache header (default: false)
ignoreSslErrorsbooleanNoAccept invalid certificates (expired, self-signed, wrong host) and turn off SSL alerts for this check (default: false)
responseTimeLimitnumberNoMax response time in milliseconds before the result is marked as slow (max 30,000)
downConfirmationAttemptsnumberNoConsecutive failures before the check is marked down (1 to 99)
recordTypesstring[]NoFor dns checks: record types to monitor, any of A, AAAA, CNAME, MX, TXT, NS, SOA (default: ["A"])
pingPacketsnumberNoNumber of ping packets for ping checks (1 to 5). Other values are ignored
timezonestringNoIANA timezone for the check (for example America/New_York)

Immediate recheck on failure is always enabled for new checks. Use Update Check to turn it off.

Default Expected Status Codes

Check typeDefault
website200, 201, 202, 204, 301, 302, 303, 307, 308, 401, 403
rest_endpoint200, 201, 202, 204, 401, 403
redirect301, 302, 303, 307, 308

Response Validation

The responseValidation object supports:

FieldTypeDescription
containsTextstring[]Strings that must appear in the response body (max 10, case-insensitive)
containsTextModestringall (default): every containsText entry must appear. any: at least one
notContainsTextstring[]Fail the check if any of these appear in the body (max 10, case-insensitive)
jsonAssertionsobject[]Several JSONPath assertions (max 20, see below). Replaces jsonPath, jsonPathOperator and expectedValue
jsonAssertionsModestringall (default): every assertion must pass (AND). any: one is enough (OR)
jsonPathstringSingle JSONPath expression (max 500 characters). Ignored when jsonAssertions is set
jsonPathOperatorstringHow to compare the JSONPath result, see operators below
expectedValueanyExpected value at the JSONPath location (strings max 1,000 characters)

Each entry in jsonAssertions has:

FieldTypeRequiredDescription
pathstringYesJSONPath, for example $.engines['mail-intake'].sinceMs (max 500 characters)
operatorstringNoDefaults to equals
expectedValueanyDependsRequired for every operator except exists. Must be a number for the greater and less operators

Operators: equals, not_equals, contains, exists, greater_than, greater_or_equal, less_than, less_or_equal.

{
  "responseValidation": {
    "notContainsText": ["maintenance"],
    "jsonAssertionsMode": "all",
    "jsonAssertions": [
      { "path": "$.status", "operator": "equals", "expectedValue": "ok" },
      { "path": "$.queue.depth", "operator": "less_than", "expectedValue": 1000 }
    ]
  }
}

Idempotency

The Idempotency-Key header is required for create requests. If you send the same key again within 24 hours, the API returns the original status and body instead of creating a duplicate check.

Keys are scoped to your account, not to a single API key. Use any unique value (for example a UUID) and generate a new one for each check you want to create.

Response

201 Created

{
  "data": {
    "id": "abc123def456"
  }
}

Only the new check ID is returned. Use Get Check to read the full check.

Error Responses

StatusDescription
400Missing Idempotency-Key, invalid request body or validation failure
403API key missing checks:write scope, the check type is not available on your plan, or the key is restricted and folder is not one of its folders
409A check already exists for this URL, the domain is already monitored, or your plan’s check limit is reached
422Malformed Idempotency-Key, or the key was already used for a different request
429Rate limit exceeded, including the check creation limits

Code Examples

cURL

curl -X POST \
  -H "X-Api-Key: ek_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-001" \
  -d '{"url": "https://example.com", "name": "My Website", "type": "website", "checkFrequency": 5}' \
  "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/checks"

JavaScript

const response = await fetch(
  "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/checks",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.EXIT1_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": `create-${Date.now()}`,
    },
    body: JSON.stringify({
      url: "https://example.com",
      name: "My Website",
      type: "website",
      checkFrequency: 5,
    }),
  }
);
const data = await response.json();
console.log(data.data.id); // New check ID

Python

import os, requests
 
response = requests.post(
    "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/checks",
    headers={
        "X-Api-Key": os.environ["EXIT1_API_KEY"],
        "Idempotency-Key": "unique-key-001",
    },
    json={
        "url": "https://example.com",
        "name": "My Website",
        "type": "website",
        "checkFrequency": 5,
    },
)
response.raise_for_status()
print(response.json())
Last updated on
Check StatsUpdate Check