Main Support

How do I use the Watchful REST API?

The REST API can be used to include Watchful data and functionality in your own applications.

Documentation & sample application

The interactive documentation will allow you to test the API without the need of a sandbox environment. Be sure to enter your API Key at the top-right.

We also recommend this tutorial on building a 1-page application in PHP with Watchful.

 

API endpoint

All API requests must be made over HTTPS to the following endpoint:

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

Calls made over plain HTTP will be redirected to HTTPS.

The API version is shown in the URLs of the endpoint, e.g. /api/v1.

Verbs

Four HTTP verbs are supported:

  • GET requests to retrieve information
  • POST to add new records
  • PUT to update records
  • DELETE requests to remove records

API keys

To use the API with your Watchful account, locate the API tab in the Watchful Settings and click the Request new API key button.

Authentication

There are two different methods to authenticate your requests to the API:

HTTP Header

You can use the http header "Api-Key" to pass your key with your request. For example:

  • GET https://app.watchful.net/api/v1/sites
  • "Api-Key: 6a7c274802f2344196b44c"

Query string parmeter

Note: This authentication method is deprecated for security reasons, but still available for testing purposes. You should avoid using it in a production application.

To authenticate your request with this method, simply append your API key in a query string parameter named "api_key". For example:

GET https://app.watchful.net/api/v1/sites?api_key=6a7c274802f2344196b44c

Formats

Date and time values are of the form YYYY-MM-DD HH:MM:SS.

Booleans are either 1 (true) or 0 (false).

Search fields can use % like in SQL and a “!” before the the value for "not".

Inputs are always in JSON.

We support 4 differents format for output. If you don’t specify an accept header, the API will return JSON format by default:

  • XML
    • HTTP-Header Accept: application/xml
  • JSON
    • HTTP-Header Accept: application/json
  • JSONP
    • HTTP-Header Accept: 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
    • HTTP-Header Accept: text/plain

Errors

All status types can be views in the interactive documentation.

Examples:

  • XML return
  • JSON return

Calls per day

We currently restrict API usage to 2000 requests per day. Please contact support if you need more calls.

Search Knowledge base

Most popular