Skip to content

Management API v3

Version:

With the Management API, you can programmatically manage checks and integrations in your account.

API Endpoints

Endpoint Name Endpoint Address
Checks
List existing checks GET https://watchgoose.com/api/v3/checks/
Get a single check GET https://watchgoose.com/api/v3/checks/<uuid>
GET https://watchgoose.com/api/v3/checks/<unique_key>
Create a new check POST https://watchgoose.com/api/v3/checks/
Update an existing check POST https://watchgoose.com/api/v3/checks/<uuid>
Pause monitoring of a check POST https://watchgoose.com/api/v3/checks/<uuid>/pause
Resume monitoring of a check POST https://watchgoose.com/api/v3/checks/<uuid>/resume
Delete check DELETE https://watchgoose.com/api/v3/checks/<uuid>
Pings
List check's logged pings GET https://watchgoose.com/api/v3/checks/<uuid>/pings/
Get a ping's logged body GET https://watchgoose.com/api/v3/checks/<uuid>/pings/<n>/body
Flips
List check's status changes GET https://watchgoose.com/api/v3/checks/<uuid>/flips/
GET https://watchgoose.com/api/v3/checks/<unique_key>/flips/
Integrations
List existing integrations GET https://watchgoose.com/api/v3/channels/
Badges
List project's badges GET https://watchgoose.com/api/v3/badges/
Service status
Check database connectivity GET https://watchgoose.com/api/v3/status/

Changes From v2

Management API v3 adds the ability to specify custom check slugs, instead of auto-generating them from check names. The Create a new check and Update an existing check calls accept a new slug parameter, and use it instead of generating the slug from the check's name.

Authentication

Your requests to Watchgoose Management API must authenticate using an API key. All API keys are project-specific. There are no account-wide API keys. By default, a project on Watchgoose doesn't have an API key. You can create read-write and read-only API keys on the Project Settings page.

read-write key
Has full access to all documented API endpoints.
read-only key

Only works with the following API endpoints:

Omits sensitive information from the API responses. See the documentation of individual API endpoints for details.

The client can authenticate itself by including an X-Api-Key: <your-api-key> header in an HTTP request. Alternatively, for POST requests with a JSON request body, the client can put an api_key field in the JSON document. See the Create a new check section for an example.

API Requests

For POST requests, the Watchgoose API expects the request body to be a JSON document (not a multipart/form-data encoded form data).

API Responses

Watchgoose uses HTTP status codes wherever possible. In general, 2xx class indicates success, 4xx indicates a client error, and 5xx indicates a server error.

The response may contain a JSON document with additional data.

Rate Limits

Avoid making more than 100 API requests per minute. If you exceed this limit, you will eventually see HTTP 429 errors.

List Existing Checks

GET https://watchgoose.com/api/v3/checks/

Returns a list of checks belonging to the user, optionally filtered by one or more tags.

Query Parameters

slug=<value>

Filters the checks and returns only the checks with the specified slug. If there are no matching checks, returns an empty list. If there are multiple matching checks, returns all of them.

Example:

https://watchgoose.com/api/v3/checks/?slug=backups

tag=<value>

Filters the checks and returns only the checks that are tagged with the specified value.

This parameter can be repeated multiple times.

Example:

https://watchgoose.com/api/v3/checks/?tag=foo&tag=bar

Response Codes

200 OK
The request succeeded.
401 Unauthorized
The API key is either missing or invalid.

Example Request

curl --header "X-Api-Key: your-api-key" https://watchgoose.com/api/v3/checks/

Example Response

{
  "checks": [
    {
      "name": "Filesystem Backup",
      "slug": "filesystem-backup",
      "tags": "backup fs",
      "desc": "Runs incremental backup every hour",
      "grace": 600,
      "n_pings": 1,
      "status": "up",
      "started": false,
      "last_ping": "2020-03-24T14:02:03+00:00",
      "next_ping": "2020-03-24T15:02:03+00:00",
      "manual_resume": false,
      "methods": "",
      "start_kw": "START",
      "success_kw": "SUCCESS",
      "failure_kw": "ERROR",
      "filter_subject": true,
      "filter_body": false,
      "filter_http_body": false,
      "filter_default_fail": false,
      "badge_url": "https://watchgoose.com/b/2/1b9d0386-d07e-44b0-8995-4a9a372de43c.svg",
      "uuid": "31365bce-8da9-4729-8ff3-aaa71d56b712",
      "ping_url": "https://watchgoose.com/ping/31365bce-8da9-4729-8ff3-aaa71d56b712",
      "update_url": "https://watchgoose.com/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712",
      "pause_url": "https://watchgoose.com/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause",
      "resume_url": "https://watchgoose.com/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume",
      "channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
      "timeout": 3600
    },
    {
      "name": "Database Backup",
      "slug": "database-backup",
      "tags": "production db",
      "desc": "Runs ~/db-backup.sh",
      "grace": 1200,
      "n_pings": 7,
      "status": "down",
      "started": false,
      "last_ping": "2020-03-23T10:19:32+00:00",
      "next_ping": null,
      "manual_resume": false,
      "methods": "",
      "start_kw": "",
      "success_kw": "",
      "failure_kw": "",
      "filter_subject": false,
      "filter_body": false,
      "filter_http_body": false,
      "filter_default_fail": false,
      "badge_url": "https://watchgoose.com/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg",
      "uuid": "803f680d-e89b-492b-82ef-2be7b774a92d",
      "ping_url": "https://watchgoose.com/ping/803f680d-e89b-492b-82ef-2be7b774a92d",
      "update_url": "https://watchgoose.com/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
      "pause_url": "https://watchgoose.com/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
      "resume_url": "https://watchgoose.com/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
      "channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
      "schedule": "15 5 * * *",
      "tz": "UTC"
    }
  ]
}

The possible values for the status field are: new, up, grace, down, and paused.

When using the read-only API key, Watchgoose omits the following fields from responses: uuid, ping_url, update_url, pause_url, resume_url, channels. It adds an extra unique_key field. The unique_key identifier is stable across API calls, and you can use it in the Get a single check and List check's status changes API calls.

Example:

{
  "checks": [
    {
      "name": "Filesystem Backup",
      "slug": "filesystem-backup",
      "tags": "backup fs",
      "desc": "Runs incremental backup every hour",
      "grace": 600,
      "n_pings": 1,
      "status": "up",
      "started": false,
      "last_ping": "2020-03-24T14:02:03+00:00",
      "next_ping": "2020-03-24T15:02:03+00:00",
      "manual_resume": false,
      "methods": "",
      "start_kw": "START",
      "success_kw": "SUCCESS",
      "failure_kw": "ERROR",
      "filter_subject": true,
      "filter_body": false,
      "filter_http_body": false,
      "filter_default_fail": false,
      "badge_url": "https://watchgoose.com/b/2/1b9d0386-d07e-44b0-8995-4a9a372de43c.svg",
      "unique_key": "a6c7b0a8a66bed0df66abfdab3c77736861703ee",
      "timeout": 3600
    },
    {
      "name": "Database Backup",
      "slug": "database-backup",
      "tags": "production db",
      "desc": "Runs ~/db-backup.sh",
      "grace": 1200,
      "n_pings": 7,
      "status": "down",
      "started": false,
      "last_ping": "2020-03-23T10:19:32+00:00",
      "next_ping": null,
      "manual_resume": false,
      "methods": "",
      "start_kw": "",
      "success_kw": "",
      "failure_kw": "",
      "filter_subject": false,
      "filter_body": false,
      "filter_http_body": false,
      "filter_default_fail": false,
      "badge_url": "https://watchgoose.com/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg",
      "unique_key": "124f983e0e3dcaeba921cfcef46efd084576e783",
      "schedule": "15 5 * * *",
      "tz": "UTC"
    }
  ]
}

Get a Single Check

GET https://watchgoose.com/api/v3/checks/<uuid>
GET https://watchgoose.com/api/v3/checks/<unique_key>

Returns a JSON representation of a single check. Accepts either check's UUID or the unique_key (a field derived from UUID and returned by API responses when using the read-only API key) as an identifier.

Response Codes

200 OK
The request succeeded.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.

Example Request

curl --header "X-Api-Key: your-api-key" https://watchgoose.com/api/v3/checks/<uuid>

Example Response

{
  "name": "Database Backup",
  "slug": "database-backup",
  "tags": "production db",
  "desc": "Runs ~/db-backup.sh",
  "grace": 1200,
  "n_pings": 7,
  "status": "down",
  "started": false,
  "last_ping": "2020-03-23T10:19:32+00:00",
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "start_kw": "START",
  "success_kw": "SUCCESS",
  "failure_kw": "ERROR",
  "filter_subject": true,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg",
  "uuid": "803f680d-e89b-492b-82ef-2be7b774a92d",
  "ping_url": "https://watchgoose.com/ping/803f680d-e89b-492b-82ef-2be7b774a92d",
  "update_url": "https://watchgoose.com/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
  "pause_url": "https://watchgoose.com/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
  "resume_url": "https://watchgoose.com/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
  "channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
  "schedule": "15 5 * * *",
  "tz": "UTC"
}

The possible values for the status field are: new, up, grace, down, and paused.

Example Read-Only Response

When using the read-only API key, Watchgoose omits the following fields from responses: uuid, ping_url, update_url, pause_url, resume_url, channels. It adds an extra unique_key field. This identifier is stable across API calls.

Note: although API omits the *_url fields in read-only API responses, the client can easily construct these URLs themselves if they know the check's unique UUID.

{
  "name": "Database Backup",
  "slug": "database-backup",
  "tags": "production db",
  "desc": "Runs ~/db-backup.sh",
  "grace": 1200,
  "n_pings": 7,
  "status": "down",
  "started": false,
  "last_ping": "2020-03-23T10:19:32+00:00",
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "start_kw": "START",
  "success_kw": "SUCCESS",
  "failure_kw": "ERROR",
  "filter_subject": true,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg",
  "unique_key": "124f983e0e3dcaeba921cfcef46efd084576e783",
  "schedule": "15 5 * * *",
  "tz": "UTC"
}

Create a Check

POST https://watchgoose.com/api/v3/checks/

Creates a new check and returns its ping URL. All request parameters are optional and will use their default values if omitted.

With this API call, you can create both Simple and Cron checks:

  • To create a Simple check, specify the timeout parameter.
  • To create a Cron check, specify the schedule and tz parameters.

Request Parameters

name

string, optional, default value: ""

Name for the new check.

Changed in API v3: the check's slug is no longer automatically generated from the check's name. Instead, the client can specify the slug explicitly via the slug field.

slug

string, optional, default value: ""

Slug for the new check. The slug should only contain the following characters: a-z, 0-9, hyphens, underscores. Example:

{"slug": "my-custom-slug"}

tags

string, optional, default value: ""

A space-delimited list of tags for the new check. Example:

{"tags": "reports staging"}

desc

string, optional.

Description of the check.

timeout

number, optional, default value: 86400.

The expected period of this check in seconds.

Minimum: 60 (one minute), maximum: 31536000 (365 days).

Example for a 5-minute timeout:

{"timeout": 300}

grace

number, optional, default value: 3600.

The grace period for this check in seconds.

Minimum: 60 (one minute), maximum: 31536000 (365 days).

schedule

string, optional.

A cron or systemd OnCalendar expression defining this check's schedule. Watchgoose will detect the expression type (cron or OnCalendar) automatically.

The schedule parameter takes precedence over the timeout field: if you specify both the timeout and the schedule parameters, Watchgoose will save the schedule and ignore the timeout.

Example using a cron expression ("run every half-hour"):

{"schedule": "0,30 * * * *"}

Example using an OnCalendar expression ("run at 12:00 of the last day of every month"):

{"schedule": "*-*~1 12:00"}

tz

string, optional, default value: "UTC".

Server's timezone. This setting only has an effect in combination with the schedule parameter.

Example:

{"tz": "Europe/Riga"}

manual_resume

boolean, optional, default value: false.

Controls whether a paused check automatically resumes when pinged (the default) or not. If set to false, a paused check will leave the paused state when it receives a ping. If set to true, a paused check will ignore pings and stay paused until you manually resume it from the web dashboard.

methods

string, optional, default value: "".

Specifies the allowed HTTP methods for making ping requests. Must be one of the two values: "" (an empty string) or "POST".

Set this field to "" (an empty string) to allow HEAD, GET, and POST requests.

Set this field to "POST" to allow only POST requests.

Example:

{"methods": "POST"}

channels

string, optional.

By default, this API call assigns no integrations to the newly created check.

Set this field to a special value "*" to automatically assign all existing integrations. Example:

{"channels": "*"}

To assign specific integrations, use a comma-separated list of integration UUIDs. You can look up integration UUIDs using the List Existing Integrations API call.

Example:

{"channels":
 "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}

Alternatively, if you have named your integrations in Watchgoose dashboard, you can specify integrations by their names. For this to work, your integrations need non-empty unique names, and they must not contain commas. The names must match exactly, whitespace is significant.

Example:

{"channels": "Email to Alice,SMS to Alice"}

unique

array of string values, optional, default value: [].

Enables "upsert" functionality. Before creating a check, Watchgoose looks for existing checks, filtered by fields listed in unique.

If Watchgoose does not find a matching check, it creates a new check and returns it with the HTTP status code 201.

If Watchgoose finds a matching check, it updates the existing check and returns it with HTTP status code 200.

The accepted values for the unique field are name, slug, tags, timeout, and grace.

Example:

{"name": "Backups", unique: ["name"]}

In this example, if a check named "Backups" exists, it will be returned. Otherwise, a new check will be created and returned.

start_kw

string, optional, default value: "".

Specifies the keywords for classifying inbound email messages and HTTP pings as start signals. Separate multiple keywords using commas. Keywords are case-sensitive.

Use this field in combination with the filter_subject, filter_body, and filter_http_body fields.

Example:

{"filter_subject": true, "start_kw": "STARTED"}

In this example, Watchgoose classifies an inbound email as a start signal if the Subject line contains the word "STARTED".

success_kw

string, optional, default value: "".

Specifies the keywords for classifying inbound email messages and HTTP pings as success signals. Separate multiple keywords using commas. Keywords are case-sensitive.

Use this field in combination with the filter_subject, filter_body, and filter_http_body fields.

Example:

{"filter_subject": true, "success_kw": "SUCCESS,COMPLETED"}

In this example, an inbound email message counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED".

failure_kw

string, optional, default value: "".

Specifies the keywords for classifying inbound email messages and HTTP pings as failure signals. Separate multiple keywords using commas. Keywords are case-sensitive.

Use this field in combination with the filter_subject, filter_body, and filter_http_body fields.

Example:

{"filter_subject": true, "failure_kw": "FAILED,ERROR"}

In this example, an inbound email message counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR".

filter_subject

boolean, optional, default value: false.

Enables filtering of inbound email messages by looking for keywords in their subject lines. See also the start_kw, success_kw, and failure_kw fields.

filter_body

boolean, optional, default value: false.

Enables filtering of inbound email messages by looking for keywords in the message body. See also the start_kw, success_kw, and failure_kw fields.

Watchgoose supports both plain text and HTML email messages, and looks for keywords both in the plain text and the HTML message contents.

filter_http_body

boolean, optional, default value: false.

Enables filtering of HTTP pings by looking for keywords in the first 10 kB of the HTTP request body. See also the start_kw, success_kw, and failure_kw fields.

filter_default_fail

boolean, optional, default value: false.

Determines the handling of email and HTTP pings when keyword filtering is enabled, but no keywords match.

Keyword filtering is enabled for inbound email messages if either filter_subject or filter_body (or both) is set to true. Keyword filtering is enabled for HTTP pings if filter_http_body is set to true.

If filter_default_fail=false, and no keywords match, the ping will be ignored.

If filter_default_fail=true, and no keywords match, the ping will be classified as a failure signal.

Example:

{
    "filter_http_body": true,
    "filter_default_fail": true,
    "success_kw": "Backup successful"
}

In this example, an HTTP ping will be classified as a success signal if and only if the request body contains the string "Backup successful". In all other cases, including HTTP GET requests with an empty request body, the ping will be classified as a failure signal.

Response Codes

201 Created
A new check was successfully created.
200 OK
An existing check was found and updated.
400 Bad Request
The request is not well-formed, violates schema, or uses invalid field values.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
The account has hit its check limit. For free accounts, the limit is 20 checks per account.

Example Request

curl https://watchgoose.com/api/v3/checks/ \
    --header "X-Api-Key: your-api-key" \
    --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'

Or, alternatively:

curl https://watchgoose.com/api/v3/checks/ \
    --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'

Example Response

{
  "name": "Backups",
  "slug": "",
  "tags": "prod www",
  "desc": "",
  "grace": 60,
  "n_pings": 0,
  "status": "new",
  "started": false,
  "last_ping": null,
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "subject": "",
  "subject_fail": "",
  "start_kw": "",
  "success_kw": "",
  "failure_kw": "",
  "filter_subject": false,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg",
  "uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
  "ping_url": "https://watchgoose.com/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "update_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "pause_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
  "resume_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
  "channels": "",
  "timeout": 3600
}

Update an Existing Check

POST https://watchgoose.com/api/v3/checks/<uuid>

Updates an existing check. All request parameters are optional. If you omit any parameter, Watchgoose will leave its value unchanged.

Request Parameters

name

string, optional.

Name for the check.

Changed in API v3: the check's slug is no longer automatically generated from the check's name. Instead, the client can specify the slug explicitly via the slug field.

slug

string, optional

Slug for the new check. The slug should only contain the following characters: a-z, 0-9, hyphens, underscores. Example:

{"slug": "my-custom-slug"}

tags

string, optional.

A space-delimited list of tags for the check.

Example:

{"tags": "reports staging"}

desc

string, optional.

Description of the check.

timeout

number, optional.

The expected period of this check in seconds.

Minimum: 60 (one minute), maximum: 31536000 (365 days).

Example for a 5-minute timeout:

{"timeout": 300}

grace

number, optional.

The grace period for this check in seconds.

Minimum: 60 (one minute), maximum: 31536000 (365 days).

schedule

string, optional.

A cron or systemd OnCalendar expression defining this check's schedule. Watchgoose will detect the expression type (cron or OnCalendar) automatically.

The schedule parameter takes precedence over the timeout field: If you specify both the timeout and the schedule parameters, Watchgoose will save the schedule and ignore the timeout.

Example using a cron expression ("run every half-hour"):

{"schedule": "0,30 * * * *"}

Example using an OnCalendar expression ("run at 12:00 of the last day of every month"):

{"schedule": "*-*~1 12:00"}

tz

string, optional.

Server's timezone. This setting only has an effect in combination with the "schedule" parameter.

Example:

{"tz": "Europe/Riga"}

manual_resume

boolean, optional, default value: false.

Controls whether a paused ping automatically resumes when pinged (the default), or not. If set to false, a paused check will leave the paused state when it receives a ping. If set to true, a paused check will ignore pings and stay paused until you manually resume it from the web dashboard.

methods

string, optional, default value: "".

Specifies the allowed HTTP methods for making ping requests. Must be one of the two values: "" (an empty string) or "POST".

Set this field to "" (an empty string) to allow HEAD, GET, and POST requests.

Set this field to "POST" to allow only POST requests.

Example:

{"methods": "POST"}

channels

string, optional.

Set this field to a special value "*" to automatically assign all existing integrations. Example:

{"channels": "*"}

Set this field to a special value "" (empty string) to automatically unassign all existing integrations. Example:

{"channels": ""}

To assign specific integrations, use a comma-separated list of integration UUIDs. You can look up integration UUIDs using the List Existing Integrations API call.

Example:

{"channels":
 "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}

Alternatively, if you have named your integrations in Watchgoose dashboard, you can specify integrations by their names. For this to work, your integrations need non-empty and unique names, and they must not contain commas. The names must match exactly, whitespace is significant.

Example:

{"channels": "Email to Alice,SMS to Alice"}

start_kw

string, optional, default value: "".

Specifies the keywords for classifying inbound email messages and HTTP pings as start signals. Separate multiple keywords using commas. Keywords are case-sensitive.

Use this field in combination with the filter_subject, filter_body, and filter_http_body fields.

Example:

{"filter_subject": true, "start_kw": "STARTED"}

In this example, Watchgoose classifies an inbound email as a start signal if the Subject line contains the word "STARTED".

success_kw

string, optional, default value: "".

Specifies the keywords for classifying inbound email messages and HTTP pings as success signals. Separate multiple keywords using commas. Keywords are case-sensitive.

Use this field in combination with the filter_subject, filter_body, and filter_http_body fields.

Example:

{"filter_subject": true, "success_kw": "SUCCESS,COMPLETED"}

In this example, an inbound email message counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED".

failure_kw

string, optional, default value: "".

Specifies the keywords for classifying inbound email messages and HTTP pings as failure signals. Separate multiple keywords using commas. Keywords are case-sensitive.

Use this field in combination with the filter_subject, filter_body, and filter_http_body fields.

Example:

{"filter_subject": true, "failure_kw": "FAILED,ERROR"}

In this example, an inbound email message counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR".

filter_subject

boolean, optional, default value: false.

Enables filtering of inbound email messages by looking for keywords in their subject lines. See also the start_kw, success_kw, and failure_kw fields.

filter_body

boolean, optional, default value: false.

Enables filtering of inbound email messages by looking for keywords in the message body. See also the start_kw, success_kw, and failure_kw fields.

Watchgoose supports both plain text and HTML email messages, and looks for keywords both in the plain text and the HTML message contents.

filter_http_body

boolean, optional, default value: false.

Enables filtering of HTTP pings by looking for keywords in the first 10 kB of the HTTP request body. See also the start_kw, success_kw, and failure_kw fields.

filter_default_fail

boolean, optional, default value: false.

Determines the handling of email and HTTP pings when keyword filtering is enabled, but no keywords match.

Keyword filtering is enabled for inbound email messages if either filter_subject or filter_body (or both) is set to true. Keyword filtering is enabled for HTTP pings if filter_http_body is set to true.

If filter_default_fail=false, and no keywords match, the ping will be ignored.

If filter_default_fail=true, and no keywords match, the ping will be classified as a failure signal.

Example:

{
    "filter_http_body": true,
    "filter_default_fail": true,
    "success_kw": "Backup successful"
}

In this example, an HTTP ping will be classified as a success signal if and only if the request body contains the string "Backup successful". In all other cases, including HTTP GET requests with an empty request body, the ping will be classified as a failure signal.

Response Codes

200 OK
The check was successfully updated.
400 Bad Request
The request is not well-formed, violates schema, or uses invalid field values.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.

Example Request

curl https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79 \
    --header "X-Api-Key: your-api-key" \
    --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'

Or, alternatively:

curl https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79 \
    --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'

Example Response

{
  "name": "Backups",
  "slug": "",
  "tags": "prod www",
  "desc": "",
  "grace": 60,
  "n_pings": 0,
  "status": "new",
  "started": false,
  "last_ping": null,
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "subject": "",
  "subject_fail": "",
  "start_kw": "",
  "success_kw": "",
  "failure_kw": "",
  "filter_subject": false,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg",
  "uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
  "ping_url": "https://watchgoose.com/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "update_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "pause_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
  "resume_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
  "channels": "",
  "timeout": 3600
}

Pause Monitoring of a Check

POST https://watchgoose.com/api/v3/checks/<uuid>/pause

Disables monitoring for a check without removing it. The check goes into a "paused" state. You can resume monitoring of the check by pinging it, or by running the Resume API call (useful when check's manual_resume=True).

This API call has no request parameters.

Response Codes

200 OK
The check was successfully paused.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.

Example Request

curl https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause \
    --request POST --header "X-Api-Key: your-api-key" --data ""

Note: the --data "" argument forces curl to send a Content-Length request header even though the request body is empty. For HTTP POST requests, the Content-Length header is sometimes required by some network proxies and web servers.

Example Response

{
  "name": "Backups",
  "slug": "",
  "tags": "prod www",
  "desc": "",
  "grace": 60,
  "n_pings": 0,
  "status": "paused",
  "started": false,
  "last_ping": null,
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "subject": "",
  "subject_fail": "",
  "start_kw": "",
  "success_kw": "",
  "failure_kw": "",
  "filter_subject": false,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg",
  "uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
  "ping_url": "https://watchgoose.com/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "update_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "pause_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
  "resume_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
  "channels": "",
  "timeout": 3600
}

Resume Monitoring of a Check

POST https://watchgoose.com/api/v3/checks/<uuid>/resume

Resumes a check. The check goes into the "new" state. Use this API call to resume the monitoring of checks that are in the paused state, and have the manual_resume configuration parameter set to True.

This API call has no request parameters.

Response Codes

200 OK
The operation was successful.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.
409 Conflict
The specified check is currently not in a paused state.

Example Request

curl https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume \
    --request POST --header "X-Api-Key: your-api-key" --data ""

Note: the --data "" argument forces curl to send a Content-Length request header even though the request body is empty. For HTTP POST requests, the Content-Length header is sometimes required by some network proxies and web servers.

Example Response

{
  "name": "Backups",
  "slug": "",
  "tags": "prod www",
  "desc": "",
  "grace": 60,
  "n_pings": 0,
  "status": "new",
  "started": false,
  "last_ping": null,
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "subject": "",
  "subject_fail": "",
  "start_kw": "",
  "success_kw": "",
  "failure_kw": "",
  "filter_subject": false,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg",
  "uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
  "ping_url": "https://watchgoose.com/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "update_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "pause_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
  "resume_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
  "channels": "",
  "timeout": 3600
}

Delete Check

DELETE https://watchgoose.com/api/v3/checks/<uuid>

Permanently deletes the check from the user's account. Returns JSON representation of the check that was just deleted.

This API call has no request parameters.

Response Codes

200 OK
The check was successfully deleted.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.

Example Request

curl https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79 \
    --request DELETE --header "X-Api-Key: your-api-key"

Example Response

{
  "name": "Backups",
  "slug": "",
  "tags": "prod www",
  "desc": "",
  "grace": 60,
  "n_pings": 0,
  "status": "new",
  "started": false,
  "last_ping": null,
  "next_ping": null,
  "manual_resume": false,
  "methods": "",
  "subject": "",
  "subject_fail": "",
  "start_kw": "",
  "success_kw": "",
  "failure_kw": "",
  "filter_subject": false,
  "filter_body": false,
  "filter_http_body": false,
  "filter_default_fail": false,
  "badge_url": "https://watchgoose.com/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg",
  "uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
  "ping_url": "https://watchgoose.com/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "update_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
  "pause_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
  "resume_url": "https://watchgoose.com/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
  "channels": "",
  "timeout": 3600
}

List check's logged pings

GET https://watchgoose.com/api/v3/checks/<uuid>/pings/

Returns a list of pings this check has received.

This endpoint returns pings in reverse order (most recent first), and the total number of returned pings depends on the account's billing plan: 100 for free accounts, 1000 for paid accounts.

Response Codes

200 OK
The request succeeded.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.

Example Request

curl https://watchgoose.com/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \
    --header "X-Api-Key: your-api-key"

Example Response

{
  "pings": [
    {
      "type": "success",
      "date": "2020-06-09T14:51:06.113073+00:00",
      "n": 4,
      "scheme": "http",
      "remote_addr": "192.0.2.0",
      "method": "GET",
      "ua": "curl/7.68.0",
      "rid": "123e4567-e89b-12d3-a456-426614174000",
      "duration": 2.896736,
      "body_url": null
    },
    {
      "type": "start",
      "date": "2020-06-09T14:51:03.216337+00:00",
      "n": 3,
      "scheme": "http",
      "remote_addr": "192.0.2.0",
      "method": "GET",
      "ua": "curl/7.68.0",
      "rid": "123e4567-e89b-12d3-a456-426614174000",
      "body_url": null
    },
    {
      "type": "success",
      "date": "2020-06-09T14:50:59.633577+00:00",
      "n": 2,
      "scheme": "http",
      "remote_addr": "192.0.2.0",
      "method": "GET",
      "ua": "curl/7.68.0",
      "rid": null,
      "duration": 2.997976,
      "body_url": null
    },
    {
      "type": "start",
      "date": "2020-06-09T14:50:56.635601+00:00",
      "n": 1,
      "scheme": "http",
      "remote_addr": "192.0.2.0",
      "method": "GET",
      "ua": "curl/7.68.0",
      "rid": null,
      "body_url": null
    }
  ]
}

Get a ping's logged body

GET https://watchgoose.com/api/v3/checks/<uuid>/pings/<n>/body

Returns a ping's logged body. The response always has the Content-Type: text/plain response header and the ping body is returned verbatim in the response body.

Response Codes

200 OK
The request succeeded and a body is present.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The check does not exist, the ping does not exist, or the ping has no body data.
503 Service Unavailable
External object storage service is unavailable, please try later.

Example Request

curl https://watchgoose.com/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body \
    --header "X-Api-Key: your-api-key"

List check's status changes

GET https://watchgoose.com/api/v3/checks/<uuid>/flips/
GET https://watchgoose.com/api/v3/checks/<unique_key>/flips/

Returns a list of "flips" this check has experienced. A flip is a change of status (from "down" to "up," or from "up" to "down").

This API endpoint supports time filtering via the seconds, start, and end query parameters. If no time filters are specified, the API returns all stored flips for a given check.

Notes about flip retention: Watchgoose stores historic flips for the current month and for two full months prior to the current month. Watchgoose cleans up older flips periodically. At any given time, there may be a low number of flips in the database that are due to be removed, but have not been removed yet. This API call will return these flips as well.

Query Parameters

seconds=<value>

Returns the flips from the last value seconds

Example:

https://watchgoose.com/api/v3/checks/<uuid|unique_key>/flips/?seconds=3600

start=<value>

Returns flips that are newer than the specified UNIX timestamp.

Example:

https://watchgoose.com/api/v3/checks/<uuid|unique_key>/flips/?start=1592214380

end=<value>

Returns flips that are older than the specified UNIX timestamp.

Example:

https://watchgoose.com/api/v3/checks/<uuid|unique_key>/flips/?end=1592217980

Response Codes

200 OK
The request succeeded.
400 Bad Request
Invalid query parameters.
401 Unauthorized
The API key is either missing or invalid.
403 Forbidden
Access denied, wrong API key.
404 Not Found
The specified check does not exist.

Example Request

curl https://watchgoose.com/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
    --header "X-Api-Key: your-api-key"

Example Response

[
    {
      "timestamp": "2020-03-23T10:18:23+00:00",
      "up": 1
    },
    {
      "timestamp": "2020-03-23T10:17:15+00:00",
      "up": 0
    },
    {
      "timestamp": "2020-03-23T10:16:18+00:00",
      "up": 1
    }
]

List Existing Integrations

GET https://watchgoose.com/api/v3/channels/

Returns a list of integrations belonging to the project.

Response Codes

200 OK
The request succeeded.
401 Unauthorized
The API key is either missing or invalid.

Example Request

curl --header "X-Api-Key: your-api-key" https://watchgoose.com/api/v3/channels/

Example Response

{
  "channels": [
    {
      "id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941",
      "name": "My Work Email",
      "kind": "email"
    },
    {
      "id": "746a083e-f542-4554-be1a-707ce16d3acc",
      "name": "My Phone",
      "kind": "sms"
    }
  ]
}

List Project's Badges

GET https://watchgoose.com/api/v3/badges/

Returns a map of all tags in the project, with badge URLs for each tag. Watchgoose provides badges in a few different formats:

  • svg: returns the badge as an SVG document.
  • json: returns a JSON document which you can use to generate a custom badge yourself.
  • shields: returns JSON in a Shields.io compatible format.

In addition, badges have 2-state and 3-state variations:

  • svg, json, shields: reports two states: "up" and "down". It considers any checks in the grace period as still "up".
  • svg3, json3, shields3: reports three states: "up", "late", and "down".

The response includes a special * entry: this pseudo-tag reports the overall status of all checks in the project.

Response Codes

200 OK
The request succeeded.
401 Unauthorized
The API key is either missing or invalid.

Example Request

curl --header "X-Api-Key: your-api-key" https://watchgoose.com/api/v3/badges/

Example Response

{
  "badges": {
    "backup": {
      "svg": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.svg",
      "svg3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.svg",
      "json": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.json",
      "json3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.json",
      "shields": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.shields",
      "shields3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.shields"
    },
    "db": {
      "svg": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.svg",
      "svg3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.svg",
      "json": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.json",
      "json3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.json",
      "shields": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.shields",
      "shields3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.shields"
    },
    "prod": {
      "svg": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.svg",
      "svg3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.svg",
      "json": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.json",
      "json3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.json",
      "shields": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.shields",
      "shields3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.shields"
    },
    "*": {
      "svg": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.svg",
      "svg3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.svg",
      "json": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.json",
      "json3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.json",
      "shields": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.shields",
      "shields3": "https://watchgoose.com/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.shields"
    }
  }
}

Check Database Connectivity

GET https://watchgoose.com/api/v3/status/

Runs a test query and returns HTTP 200 if the query completes successfully. Use this endpoint to monitor the uptime of your Healthchecks instance with an external uptime monitoring system.

Response Codes

200 OK
The request succeeded.
500 Internal Server Error
Test database query did not succeed.