Use the Watchful REST API

The Watchful REST API lets you connect Watchful with your own applications, scripts, dashboards, and other tools.

Using the API, developers can retrieve Watchful data and perform supported actions programmatically instead of working exclusively through the Watchful interface.

Watchful REST API documentation

Watchful provides interactive API documentation that lets you explore available endpoints and test API requests directly.

To use the interactive documentation:

1. Open the Watchful REST API documentation.
2. Click the Authorize button in the top-right corner and enter your API key.
3. Select the endpoint you want to test.
4. Configure the request parameters as required.
5. Run the request and review the response.

The interactive documentation is useful for testing API calls without setting up a separate sandbox environment.

Get your API key

You need an API key to authenticate requests made to the Watchful REST API.

To request an API key:

1. Log in to your Watchful account.
2. Openthe Settings area on the left toolbar.
3. Select the API tab.
4. Click Request new API key.

Keep your API key private. Anyone with access to the key may be able to make API requests using your Watchful account.

API endpoint

All Watchful REST API requests should be sent over HTTPS to:

• https://app.watchful.net/api/v1

The API version is included in the endpoint URL. In this example, v1 identifies version 1 of the API.

Requests made using plain HTTP are redirected to HTTPS.

Supported request methods

The Watchful REST API supports the standard HTTP methods:

• GET — retrieve information
• POST — add new records
• PUT — update existing records
• DELETE — remove records

The methods available for a particular resource are documented in the interactive API documentation.

Authenticate API requests

The recommended way to authenticate with the Watchful REST API is to send your API key in the HTTP header.

Use the Api-Key header with each request.

For example:

• GET https://app.watchful.net/api/v1/sites
• Api-Key: YOUR_API_KEY

Authentication using a query string

Watchful also supports passing the API key as an api_key query parameter.

For example:

• GET https://app.watchful.net/api/v1/sites?api_key=YOUR_API_KEY

However, this authentication method is deprecated for security reasons and should only be used for testing. Use the Api-Key HTTP header for production integrations. Watchful – the webmaster toolbox

Data formats

Inputs sent to the Watchful REST API use JSON.

Unless you specify another format using the Accept header, responses are returned as JSON by default.

Supported response formats include:

• JSON — application/json
• XML — application/xml
• JSONP — application/json
  • For JSONP, add the ?callback parameter to any GET call to have the results wrapped in a JSON function. For example: https://app.watchful.net/api/v1/sites?callback=myfunction
• Serialized output — text/plain

Date, time, Boolean, and search values

The Watchful REST API uses the following conventions:

• Dates and times
  • YYYY-MM-DD HH:MM:SS
• Boolean values
  • 1 = true
  • 0 = false
• Search values
  • Search fields can use % as a wildcard.
  • You can also place ! before a value to indicate “not.”

API request limits

Watchful currently limits API usage to 2,000 requests per day.

If your integration requires a higher request limit, contact Watchful Support to discuss your requirements.

Test your integration before deploying it

The interactive API documentation is the easiest place to experiment with the Watchful REST API before adding requests to your own application.

Once your requests are working as expected, use header-based authentication and HTTPS when implementing the integration in production.