Gatus

https://gatus.io/docs
Admin
Gatus is an automated service health dashboard and uptime monitoring tool that allows users to...
Tokens:20,970
Snippets:224
Trust Score:8.9
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example gRPC Conditions

Source: https://gatus.io/docs/monitoring-grpc

Example conditions for a gRPC endpoint that verify connection, serving status, and response time.

```text
[CONNECTED] == true
[BODY].status == SERVING
[RESPONSE_TIME] < 2000
```

--------------------------------

### Dark theme custom CSS example

Source: https://gatus.io/docs/appearance

Example custom CSS that creates a dark theme for the status page. Applies to Business and Enterprise plans. Uses selectors like #global, .dashboard-container, .endpoint, .endpoint-group, and announcement selectors.

```css
/* Dark theme example */
#global {
  background-color: #1a1a1a;
  color: #ffffff;
}

.dashboard-container {
  background-color: #2a2a2a;
}

.endpoint, .endpoint-group {
  background-color: #333333;
  border: 1px solid #444444;
}

.endpoint-header, .endpoint-group-header {
  background-color: #404040;
  color: #ffffff;
}

.endpoint-content, .endpoint-group-content {
  background-color: #333333;
  color: #e0e0e0;
}

.announcement-container {
  background-color: #333333;
  border: 1px solid #444444;
}

.announcement-header {
  background-color: #404040;
  color: #ffffff;
}

.announcement-content {
  background-color: #333333;
  color: #e0e0e0;
}
```

--------------------------------

### Example: Authentication and API Testing Suite Configuration

Source: https://gatus.io/docs/suites

A suite that performs login, creates a resource, verifies it, and deletes it. Uses initial context for base_url, username, and password. Stores token and resource_id from responses. Uses AlwaysRun on the delete endpoint for cleanup.

```yaml
# Initial Context
base_url: https://api.example.com
username: testuser
password: test123

# Endpoint 1: Login
URL: [CONTEXT].base_url/auth/login
Method: POST
Body: {"username": "[CONTEXT].username", "password": "[CONTEXT].password"}
Store: token from [BODY].token

# Endpoint 2: Create Resource
URL: [CONTEXT].base_url/resources
Method: POST
Headers: Authorization: Bearer [CONTEXT].token
Body: {"name": "Test Resource"}
Store: resource_id from [BODY].id

# Endpoint 3: Verify Resource
URL: [CONTEXT].base_url/resources/[CONTEXT].resource_id
Method: GET
Headers: Authorization: Bearer [CONTEXT].token
Conditions: [STATUS] == 200, [BODY].name == "Test Resource"

# Endpoint 4: Delete Resource
URL: [CONTEXT].base_url/resources/[CONTEXT].resource_id
Method: DELETE
Headers: Authorization: Bearer [CONTEXT].token
AlwaysRun: true
```

--------------------------------

### Validate JSON response body with [BODY]

Source: https://gatus.io/docs/monitoring-http

Example JSON response body and corresponding conditions that all pass, demonstrating how to validate JSON paths, use pat and any functions, and access array elements.

```json
{
  "article": {
    "id": 123,
    "title": "Hello, world!",
    "author": "John Doe",
    "tags": ["hello", "world"]
  }
}
```

```text
has([BODY].article) == true

[BODY].article.id == 123
[BODY].article.id > 0

[BODY].article.title == Hello, world!
[BODY].article.title == pat(*world*)
len([BODY].article.title) > 0
len([BODY].article.title) == 13

[BODY].article.author == John Doe
[BODY].article.author == any(John Doe, Jane Doe, Bob)

len([BODY].article.tags) == 2
[BODY].article.tags[0] == hello
[BODY].article.tags[1] == world
```

--------------------------------

### Example YAML configuration for import

Source: https://gatus.io/docs/import-yaml-configuration

A valid Gatus YAML configuration that can be imported into Gatus.io. It includes endpoints, external-endpoints, and alerting provider configurations. Use this as a template for migrating your self-hosted Gatus configuration.

```yaml
endpoints:
  - name: website
    url: https://example.com
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 1000"
      
  - name: api
    group: backend
    url: https://api.example.com/health
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == UP"
    alerts:
      - type: slack
        
  - name: database
    group: backend
    url: tcp://db.example.com:5432
    interval: 30s
    conditions:
      - "[CONNECTED] == true"

external-endpoints:
  - name: batch-job
    group: jobs
    token: abcd1234
    alerts:
      - type: pagerduty
        failure-threshold: 2

alerting:
  slack:
    webhook-url: https://hooks.slack.com/services/...
  pagerduty:
    integration-key: your-integration-key
```

--------------------------------

### Condition Using [DOMAIN_EXPIRATION] placeholder

Source: https://gatus.io/docs/monitoring-domain-expiration

Example of a Gatus condition checking that the domain expiration is greater than 720 hours (30 days). The value resolves to a duration.

```generic
[DOMAIN_EXPIRATION] > 720h
```

--------------------------------

### GET /api/v1/external/status-pages/{id}

Source: https://gatus.io/docs/api

Retrieves the configuration of a specific status page. Requires READ authentication.

```APIDOC
## GET /api/v1/external/status-pages/{id}

### Description
Retrieves the status page configuration for the specified status page ID.

### Method
GET

### Endpoint
/api/v1/external/status-pages/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the status page.

### Authentication
Requires a READ token or user API key. Use the Authorization header: `Authorization: Bearer YOUR_TOKEN_HERE`.

### Request Example
```
curl -X GET "https://gatus.io/api/v1/external/status-pages/123" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
Returns the status page configuration in JSON format.

#### Response Example
(No explicit response example provided in the source.)
```

--------------------------------

### Pushing a successful result with curl

Source: https://gatus.io/docs/monitoring-push-based

Example curl command to push a successful result to an external endpoint. Replace the domain, key, and token with your own values. The success parameter is set to true.

```bash
curl -X POST -H "Authorization: Bearer 12345678" status.example.org/api/v1/endpoints/my-group_my-service/external?success=true
```

--------------------------------

### Pushing an unsuccessful result with curl

Source: https://gatus.io/docs/monitoring-push-based

Example curl command to push an unsuccessful result to an external endpoint. Replace the domain, key, and token with your own values. The success parameter is set to false.

```bash
curl -X POST -H "Authorization: Bearer 12345678" status.example.org/api/v1/endpoints/my-group_my-service/external?success=false
```

--------------------------------

### [CONNECTED] Placeholder

Source: https://gatus.io/docs/monitoring-grpc

Placeholder that checks whether the gRPC connection was successfully established.

```text
[CONNECTED] == true
```

--------------------------------

### Retrieve Status Page Configuration with curl

Source: https://gatus.io/docs/api

Fetches the configuration for a status page by ID using a READ token. Replace YOUR_TOKEN_HERE with a valid token.

```bash
curl -X GET "https://gatus.io/api/v1/external/status-pages/123" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

--------------------------------

### Uptime badge URL

Source: https://gatus.io/docs/badges

Generates a badge showing uptime over the past 1, 24, 7, or 30 days. Replace {key} with the endpoint key.

```text
/api/v1/endpoints/{key}/uptimes/1h/badge.svg

```

```text
/api/v1/endpoints/{key}/uptimes/24h/badge.svg

```

```text
/api/v1/endpoints/{key}/uptimes/7d/badge.svg

```

```text
/api/v1/endpoints/{key}/uptimes/30d/badge.svg

```

--------------------------------

### [RESPONSE_TIME] Placeholder

Source: https://gatus.io/docs/monitoring-grpc

Placeholder that checks the response time of the health check request in milliseconds.

```text
[RESPONSE_TIME] < 1000
```

--------------------------------

### POST /api/v1/external/status-pages/{id}/endpoints

Source: https://gatus.io/docs/api

Creates a new endpoint for a status page. Requires WRITE authentication.

```APIDOC
## POST /api/v1/external/status-pages/{id}/endpoints

### Description
Creates a new endpoint for the specified status page.

### Method
POST

### Endpoint
/api/v1/external/status-pages/{id}/endpoints

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the status page.

#### Request Body
- **name** (string) - Required - The name of the endpoint.
- **group** (string) - Optional - The group to which the endpoint belongs.
- **url** (string) - Required - The URL to monitor.
- **interval** (string) - Optional - The monitoring interval (e.g., "30s").
- **conditions** (array of strings) - Optional - Conditions for the endpoint (e.g., "[STATUS] == 200").

### Authentication
Requires a WRITE token or user API key. Use the Authorization header: `Authorization: Bearer YOUR_TOKEN_HERE`.

### Request Example
```
curl -X POST "https://gatus.io/api/v1/external/status-pages/123/endpoints" \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "group": "Production",
    "url": "https://api.example.com/health",
    "interval": "30s",
    "conditions": [
      "[STATUS] == 200",
      "[RESPONSE_TIME] < 1000"
    ]
  }'
```

### Response
#### Success Response (200)
Returns the created endpoint configuration in JSON format.

#### Response Example
(No explicit response example provided in the source.)
```

--------------------------------

### Monitor certificate expiration with [CERTIFICATE_EXPIRATION]

Source: https://gatus.io/docs/monitoring-http

Condition that passes when the endpoint's certificate expires in more than 72 hours.

```text
[CERTIFICATE_EXPIRATION] > 72h
```

--------------------------------

### Response time badge URL

Source: https://gatus.io/docs/badges

Generates a badge showing average response time over the past 1, 24, 7, or 30 days. Replace {key} with the endpoint key.

```text
/api/v1/endpoints/{key}/response-times/1h/badge.svg

```

```text
/api/v1/endpoints/{key}/response-times/24h/badge.svg

```

```text
/api/v1/endpoints/{key}/response-times/7d/badge.svg

```

```text
/api/v1/endpoints/{key}/response-times/30d/badge.svg

```

--------------------------------

### [BODY] Placeholder

Source: https://gatus.io/docs/monitoring-grpc

Placeholder that checks the serving status returned by the health check. The response is in JSON format with a "status" field. Common status values include SERVING, NOT_SERVING, and UNKNOWN.

```text
[BODY].status == SERVING
```

--------------------------------

### Monitor HTTP status code with [STATUS]

Source: https://gatus.io/docs/monitoring-http

Condition that passes when the HTTP response status code is exactly 200.

```text
[STATUS] == 200
```

--------------------------------

### String Search Condition

Source: https://gatus.io/docs/monitoring-http

Condition to search for a string in the response body using a pattern.

```APIDOC
## [BODY] == pat(*john*)

### Description
Search for a specific string in the response body using a pattern.

### Method
GET

### Endpoint
Any HTTP endpoint

### Parameters
#### Condition
- `[BODY]` (string) - Required - The response body content.
- `pat(pattern)` (string) - Required - The pattern to search for, using wildcards.

### Request Example
```
[BODY] == pat(*john*)
```

### Response
#### Success Response (200)
- **condition** (boolean) - True if the pattern matches the response body.

#### Response Example
```
true
```
```

--------------------------------

### Create a New Endpoint with curl

Source: https://gatus.io/docs/api

Adds a new HTTP endpoint to a status page using a WRITE token. The request body includes name, group, URL, interval, and conditions.

```bash
curl -X POST "https://gatus.io/api/v1/external/status-pages/123/endpoints" \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "group": "Production",
    "url": "https://api.example.com/health",
    "interval": "30s",
    "conditions": [
      "[STATUS] == 200",
      "[RESPONSE_TIME] < 1000"
    ]
  }'
```

--------------------------------

### Health badge URL

Source: https://gatus.io/docs/badges

Generates a badge showing whether the endpoint is healthy or not. Replace {key} with the endpoint key.

```text
/api/v1/endpoints/{key}/health/badge.svg

```

--------------------------------

### POST request URL for pushing status to external endpoint

Source: https://gatus.io/docs/monitoring-push-based

Send a POST request to this URL to push a status to your Gatus dashboard. Replace {key} with the pattern <GROUP_NAME>_<ENDPOINT_NAME> (lowercased) with special characters replaced by '-'. The query parameters include success (boolean), error (optional string), and duration (optional duration string). Include an Authorization header with value 'Bearer <TOKEN>'.

```http
status.yourcompany.com/api/v1/endpoints/{key}/external?success={success}&error={error}&duration={duration}
```

--------------------------------

### Search response body for string with pat

Source: https://gatus.io/docs/monitoring-http

Condition that passes when the response body contains the string 'john' (case-sensitive) using the pat function.

```text
[BODY] == pat(*john*)
```
Tokens:
Raw