API Documentation v1.1

API: Retrieving Data

Communication to and from our API is done through HTTP GET and POST queries. We support two basic formats for output : JSON and XML. You can access our API from almost any programming language, and in just a few minutes with our plug and play libraries.



You can search for logs via our API services with GET request. Each request made match a method of the API on our servers. To make the best use of the public API, you should understand the difference between GET and POST methods, in which cases and how to use them.



Data Params

When searching for logs from our API servers, you can specify the following parameters (only API Key is mandatory) with their respective values.


  1. apikey: Your API Key. You can find this from your Account Settings page.
  2. q: A query string. All logs matching this string will be returned.
  3. from: Start timestamp for the search. Defaults to “-24h”.
  4. until: End timestamp for the search. Defaults to “now”.
  5. format: The format of response you want back from the server. JSON or XML. Default is JSON.
  6. type: Filter the log type that you want to search. INFO, WARNING or ERROR. Default is INFO. For multiple types please use type[].
  7. order: Direction of results returned, either “asc” or “desc”. Defaults to “desc”.
  8. limit: Number of rows returned by search. Defaults to 5.



GET Requests

Data retrieving can be done via GET requests. A simple CURL request would look something like the one below:
curl -g --request GET "https://logs.ws/api/1.1/?apikey=API_KEY&q=Search Query"

For example, if your want to search the last 2 records in descending order for ERROR and WARNING log types in JSON format using API key "123", starting from the last 24 hours till now with the query string "Line Number", The final cURL command must be :

curl -g --request GET "https://logs.ws/api/1.1/?apikey=123&q=Line Number&from=1511427381&until=1511513781&format=xml&type[]=error&type[]=warning&order=asc&limit=2"

Try Online

You can also try an online demo to see a working version at apibin.org.
Please note that the API key being used at the online demo will not work from any other source since we have added the IP of apibin.org in our whitelist.



Response

The response is sent from the API server in either JSON or XML format depending on the format you have specified when making the request.

Following are examples of success response:

JSON

[
    {"hash":"13111c20aee51aeb480ecbd988cd8cc9","date":1400598006,"type":"INFO","remote_ip":"199.79.62.39","log":"Test Log 1"},
    {"hash":"14ea0d5b0cf49525d1866cb1e95ada5d","date":1400596202,"type":"INFO","remote_ip":"199.79.62.39","log":"Test Log 2"}
]

XML

<?xml version='1.0' encoding='UTF-8'?>
<logs>
    <event>
        <hash>13111c20aee51aeb480ecbd988cd8cc9</hash>
        <date>1400598006</date>
        <type>INFO</type>
        <remote_ip>199.79.62.39</remote_ip>
        <log>Test Log 1</log>
    </event>
    <event>
        <hash>14ea0d5b0cf49525d1866cb1e95ada5d</hash>
        <date>1400596202</date>
        <type>INFO</type>
        <remote_ip>199.79.62.39</remote_ip>
        <log>Test Log 2</log>
    </event>
</logs>

Following are examples of error response:

JSON

{"result":false,"message":"Error 106: Invalid API key"}
Or, if there are no logs
{"result":false,"message":"Error 111: No data found"}

XML

<?xml version='1.0' encoding='UTF-8'?>
<output>
<result>false</result>
<message>Error 106: Invalid API key</message>
</output>
Or, if there are no logs
<?xml version='1.0' encoding='UTF-8'?>
<output>
<result>false</result>
<message>Error 111: No data found</message>
</output>



Error Messages And Their Interpretation

The following is a compiled list of error messages you might encounter when receiving request from our API server:

Error No.Error MessageMeaning
101 API key unspecified API key is mandatory and you did not specify any. You can find your API key under your Account Settings page.
102 Log not specified You are tying to add an empty log. A log should at least be 1 char in length.
103 The IP xxx.xxx.xx.x is not recognized as a valid IP. The request is originating from an IP address that is not specified in your whitelist. You can add an IP to your whitelist from your Account Settings page.
105 There was an error adding your log. We have been intimated about this and we are fixing it. Some internal glitch happened and we have been intimated about it. We will be fixing up the problem ASAP.
106 Invalid API key You have specified an incorrect API key. You can find your API key under your Account Settings page.
110 Unsupported method. Use POST to add logs. You are using a method that is not supported for adding logs. You should always use a POST method to add logs.
111 No data found. Your search parameters could not find any logs.