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

You have three different methods to authenticate yourself to the API:

  1. HTTP Header
  2. Query parmeter
    • API Key in the query string
    • GET https://app.watchful.li/api/v1/sites?api_key=6a7c274802f2344196b44c
  3. Session Login
    • You can access to all the resources  if you are logged into Watchful . To use your session login, just provide your user name and password at the login screen and then make a request through your browser or with the interactive documenation.

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