Main Support

How do I use the Watchful REST API?

Users on all plans can use the REST (API) to query and update their Watchful data. Please review this video before proceeding:

 

Note: To test the API, please visit the interactive documentation.

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 endpoint

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

https://app.watchful.li/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.

Resources

You will find all the resources of the API on our interactive documentation.

API keys

To use the API with your Watchful account, select the API tab in your Profile and click the Request new API key button as shown in the screenshot below.

12-api-key

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.li/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.li/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.li/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 your API usage to 2000 requests per day. Please open a support ticket if you need more calls.

PHP examples