Sites Configuration

Configure sites to monitor with different check types and options

The sites array in your .upptimerc.yml file defines which endpoints to monitor. Upptime supports multiple check types including HTTP(S), TCP ping, and DNS queries.

Basic Site Configuration

The simplest site configuration requires just a name and URL:

sites:
  - name: Google
    url: https://www.google.com

Site Parameters

name · string · required

A descriptive name for your site. This appears on the status page and in issue titles.

- name: My Website

url · string · required

The URL or hostname to monitor. Format depends on the check type.

For HTTP(S) checks:

- name: Google
  url: https://www.google.com

For TCP ping:

- name: IPv6 test
  url: forwardemail.net
  check: "tcp-ping"
  port: 80

check · string · default: "http"

The type of check to perform. Available options:

• http or https - HTTP(S) request (default)
• tcp-ping - TCP connection test
• dns - DNS lookup

- name: DNS Test
  url: google.com
  check: dns

port · number

The port to use for TCP ping checks.

- name: Mail Server
  url: mail.example.com
  check: "tcp-ping"
  port: 25

ipv6 · boolean · default: "false"

Use IPv6 instead of IPv4 for the check.

- name: IPv6 Test
  url: forwardemail.net
  port: 80
  check: "tcp-ping"
  ipv6: true

HTTP/HTTPS Options

method · string · default: "GET"

HTTP method to use. Options: GET, POST, PUT, DELETE, HEAD, etc.

- name: API Endpoint
  url: https://api.example.com/health
  method: POST

headers · array

Custom HTTP headers to send with the request.

- name: Authenticated API
  url: https://api.example.com/status
  headers:
    - "Authorization: Bearer $API_TOKEN"
    - "Content-Type: application/json"

Use GitHub Secrets for sensitive values like API tokens. Reference them with $SECRET_NAME.

body · string

Request body to send with POST/PUT requests.

- name: API Health Check
  url: https://api.example.com/health
  method: POST
  body: '{"status": "check"}'

expectedStatusCodes · array · default: "[200]"

HTTP status codes that indicate a successful check. By default, only 200 is considered successful.

- name: Redirect Test
  url: https://example.com/redirect
  expectedStatusCodes:
    - 200
    - 301
    - 302

maxResponseTime · number · default: "30000"

Maximum response time in milliseconds before considering the site as slow or down.

- name: Fast API
  url: https://api.example.com
  maxResponseTime: 5000

maxRedirects · number · default: "5"

Maximum number of redirects to follow.

- name: Example
  url: https://example.com
  maxRedirects: 3

Authentication

__dangerous__insecure__ · boolean · default: "false"

Skip SSL certificate verification. Only use this for testing.

- name: Test Site
  url: https://self-signed.example.com
  __dangerous__insecure__: true

Only use this for development. Never skip SSL verification in production.

Response Validation

slug · string

Custom slug for the site’s URL path. By default, generated from the name.

- name: My Website
  url: https://example.com
  slug: example

icon · string

Custom icon URL for the site. By default, uses the favicon from the site.

- name: My Site
  url: https://example.com
  icon: https://example.com/icon.png

Example Configurations

Basic HTTP Check

sites:
  - name: Google
    url: https://www.google.com

API with Authentication

sites:
  - name: Private API
    url: https://api.example.com/v1/health
    method: GET
    headers:
      - "Authorization: Bearer $API_TOKEN"
    expectedStatusCodes:
      - 200
      - 201

TCP Port Check

sites:
  - name: Mail Server
    url: mail.example.com
    check: "tcp-ping"
    port: 587

IPv6 Check

sites:
  - name: IPv6 Test
    url: forwardemail.net
    port: 80
    check: "tcp-ping"
    ipv6: true

POST Request with Body

sites:
  - name: Webhook
    url: https://api.example.com/webhook
    method: POST
    headers:
      - "Content-Type: application/json"
    body: '{"event": "health_check"}'
    expectedStatusCodes:
      - 200
      - 202

Multiple Status Codes

sites:
  - name: CDN Endpoint
    url: https://cdn.example.com/asset
    expectedStatusCodes:
      - 200
      - 304  # Not Modified
    maxResponseTime: 2000

Best Practices

Use descriptive names

Choose clear, descriptive names that help you quickly identify which service is down when you receive an alert.

# Good
- name: Production API - User Service
  url: https://api.example.com/users

# Not as clear
- name: API
  url: https://api.example.com/users

Set realistic timeouts

Set maxResponseTime based on your service’s typical response time. Too low and you’ll get false alarms; too high and you won’t catch performance issues.

- name: Database API
  url: https://db-api.example.com/health
  maxResponseTime: 5000  # 5 seconds for database queries

Use secrets for sensitive data

Never commit API tokens or passwords directly in .upptimerc.yml. Use GitHub Secrets instead.

# In .upptimerc.yml
- name: Private API
  url: https://api.example.com
  headers:
    - "Authorization: Bearer $API_TOKEN"

# Add API_TOKEN as a GitHub Secret in your repository settings

Monitor critical paths

Monitor the most critical user-facing endpoints, not just your homepage.

sites:
  - name: Homepage
    url: https://example.com
  - name: Login API
    url: https://api.example.com/auth/login
  - name: Payment Gateway
    url: https://api.example.com/payments/status

Next Steps

Configuration Reference

Complete .upptimerc.yml reference

Customize Status Page

Customize the appearance of your status page