NAV
HTTP cURL

Introduction

Welcome to the Access Watch API!

Our API is primarily about analyzing web traffic:

You can also use our API to get information about IP Addresses and User Agents.

Authentication

GET /1.2/hello HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json

curl "https://api.access.watch/1.2/hello" \
  -H "Api-Key: <Api_Key>"

Access Watch use API keys to authorize access to our API.

To get an API key, send us an email at [email protected] and we will come back to you.

The API key is expected to be passed in each request with the Api-Key HTTP Header:

Api-Key: <API_KEY>

We also support the api_key parameter in the URL:

GET https://api.access.watch/1.2/hello?api_key=<API_KEY>

Database API

IP Address

This endpoint is used to get metadata and reputation of an IP Address.

API Request

GET /1.2/database/address/92.78.176.182 HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json

curl "https://api.access.watch/1.2/database/address/92.78.176.182" \
  -H "Api-Key: <Api_Key>"

GET https://api.access.watch/1.2/database/address/<ADDRESS>

URL Parameters

Parameter Type Default Description
include_robots int 0 include the robots in the response

API Response

JSON Response example (ok IP address):

{
  "id": "e90d9f20cce9c203f439129b0943a8bb",
  "value": "92.78.176.182",
  "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
  "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
  "as_number": "3209",
  "network_name": "ARCOR-DSL-NET17",
  "country_code": "DE",
  "flags": [
    "broadband"
  ],
  "reputation": {
    "status": "ok",
    "threats": []
  }
}

JSON Response example (suspicious IP address):

{
  "id": "a46c391e4a75e4a3734042b6077e8cfc",
  "value": "91.200.12.5",
  "hostname": "4.xrfuwuqi.com",
  "label": "4.xrfuwuqi.com",
  "as_number": "35804",
  "network_name": "VHOSTER-NET",
  "country_code": "UA",
  "flags": [
    "server"
  ],
  "reputation": {
    "status": "bad",
    "threats": [
      "suspicious_scan",
      "comment_spam",
      "brute_force_login"
    ]
  }
}

Return an Address object with extra properties:

Optionnally:

Check the examples on the side.

Properties of the JSON response object

Parameter Type Description
id string internal identifier
value string the ipv4 or ipv6 address
hostname string the reverse hostname for the address
label string a human label for the address (currently hostname or value)
as_number string the autonomous system number
network_name string the network name
country_code string the country code, two letter (ISO 3166-1 alpha-2)
first_activity string first Date & Time of activity, ISO8601 format
last_activity string last Date & Time of activity, ISO8601 format
flags array see flags in the the Address object section
robots array an array of Robot objects
reputation object a Reputation object

Robot

This endpoint is used to get metadata and reputation of a Robot.

API Request

GET /1.2/database/robot/mars HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json

curl "https://api.access.watch/1.2/database/robot/mars" \
  -H "Api-Key: <Api_Key>"

GET https://api.access.watch/1.2/database/robot/<ID>

URL Parameters

Parameter Type Default Description
include_addresses int 0 include the addresses in the response

API Response

JSON Response example (ok IP address):

{
  "id": "4c0cb48f-fdb3-4ac3-b333-bebcf49e80dd",
  "name": "Mars",
  "label": "Brute Force Bot",
  "description": "Brute Force Robot targeting WordPress websites. Distributing attacks over thousands of IP addresses.",
  "url": "https:\/\/access.watch\/database\/robots\/bad\/mars",
  "icon": "https:\/\/api.access.watch\/1.1\/icon\/robot\/4c0cb48f-fdb3-4ac3-b333-bebcf49e80dd",
  "flags": [],
  "reputation": {
    "status": "bad",
    "threats": [
      "brute_force_login"
    ]
  },
  "first_activity": "2015-09-11T16:15:21.000000Z",
  "last_activity": "2017-11-29T09:23:46.000000Z"
}

Return a Robot object with extra properties:

Optionnally:

Check the example on the side.

Properties of the JSON response object

Parameter Type Description
id string a unique identifier
name string name of the robot for humans
label string short description of the purpose and/or reputation
description string description of the robot, its purpose
url string url of the robot entry in the Access Watch database
icon string url of an svg icon representing the robot
flags array see flags in the the Robot object section
reputation object a Reputation object
first_activity string first Date & Time of activity, ISO8601 format
last_activity string last Date & Time of activity, ISO8601 format

Luna API

IP Address

This endpoint is used to get metadata and reputation of an IP Address.

API Request

GET /1.1/address/92.78.176.182 HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json

curl "https://api.access.watch/1.1/address/92.78.176.182" \
  -H "Api-Key: <Api_Key>"

GET https://api.access.watch/1.1/address/<ADDRESS>

API Response

JSON Response example (ok IP address):

{
  "id": "e90d9f20cce9c203f439129b0943a8bb",
  "value": "92.78.176.182",
  "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
  "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
  "as_number": "3209",
  "network_name": "ARCOR-DSL-NET17",
  "country_code": "DE",
  "flags": [
    "broadband"
  ],
  "reputation": {
    "status": "ok",
    "threats": []
  }
}

JSON Response example (suspicious IP address):

{
  "id": "a46c391e4a75e4a3734042b6077e8cfc",
  "value": "91.200.12.5",
  "hostname": "4.xrfuwuqi.com",
  "label": "4.xrfuwuqi.com",
  "as_number": "35804",
  "network_name": "VHOSTER-NET",
  "country_code": "UA",
  "flags": [
    "server"
  ],
  "reputation": {
    "status": "bad",
    "threats": [
      "suspicious_scan",
      "comment_spam",
      "brute_force_login"
    ]
  }
}

Return an Address object with extra properties:

Check the examples on the side.

Properties of the JSON response object

Parameter Type Description
id string internal identifier
value string the ipv4 or ipv6 address
hostname string the reverse hostname for the address
label string a human label for the address (currently hostname or value)
as_number string the autonomous system number
network_name string the network name
country_code string the country code, two letter (ISO 3166-1 alpha-2)
flags array see flags in the the Address object section
robots array an array of Robot objects
reputation object a Reputation object

User Agent

POST /1.1/user-agent HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
}

curl "https://api.access.watch/1.1/user-agent" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{"value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"}'

JSON Response example:

{
  "id": "480216f",
  "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36",
  "type": "browser",
  "agent": {
    "name": "chrome",
    "icon": "chrome",
    "version": "49.0.2623.87",
    "label": "Chrome 49"
  },
  "system": {
    "name": "macosx",
    "icon": "macosx",
    "version": "10.11.3",
    "label": "OS X 10.11"
  }
}

This endpoint is used to get metadata about a User Agent string.

API Request

POST https://api.access.watch/1.1/user-agent

This endpoint accept a JSON object as input.

The expected Content-Type is “application/json”.

JSON Input Properties

Parameter Type Required Description
value string yes the user agent string

API Response

Return a User Agent object, see the example on the side.

To learn more about the properties, see the User Agent object table.

Check the examples on the side.

Headers Signature

Request with raw headers:

POST /1.1/signature HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
  "Accept-Encoding": "gzip, deflate, sdch",
  "Accept-Language": "en-US,en;q=0.8",
  "Cache-Control": "max-age=0",
  "Connection": "keep-alive",
  "DNT": "1",
  "Host": "francois.hodierne.net",
  "Referer": "https://www.google.com/",
  "Upgrade-Insecure-Requests": "1",
  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
}

curl "https://api.access.watch/1.1/signature" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
  "Accept-Encoding": "gzip, deflate, sdch",
  "Accept-Language": "en-US,en;q=0.8",
  "Cache-Control": "max-age=0",
  "Connection": "keep-alive",
  "DNT": "1",
  "Host": "francois.hodierne.net",
  "Referer": "https://www.google.com/",
  "Upgrade-Insecure-Requests": "1",
  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
}'

This endpoint is used to get information about an agent, by parsing the HTTP Headers.

Informations about the agent are extracted and you get back an identifier, user agent, mime type and language.

API Request

POST https://api.access.watch/1.1/signature

The expected Content-Type is “application/json”.

Keys are not case sensitive, so it’s ok if they are submitted all lowercase or uppercase.

We recommand to remove sensitive data like Cookie or Authorization headers.

API Response

JSON Response example (good reputation):

{
  "id": "7ecc3a36d6eae49e535f7a956778a166",
  "language_code": "en",
  "country_code": "US",
  "user_agent": {
    "id": "b516786e573a426eb842ec2132ed35e2",
    "type": "browser",
    "agent": {
      "name": "chrome",
      "icon": "chrome",
      "label": "Chrome 49.0.2623.87"
    },
    "system": {
      "name": "macosx",
      "icon": "macosx",
      "label": "MacOS X 10.11.3"
    }
  },
  "reputation": {
    "threats": [],
    "status": "nice"
  }
}

JSON Response example (bad reputation):

{
  "id": "e487849551a056762249e1d266bef465",
  "language_code": "en",
  "country_code": "US",
  "user_agent": {
    "id": "aee5c2d9c2fc59e1b95d344382a89a31",
    "type": "browser",
    "agent": {
      "name": "firefox",
      "icon": "firefox",
      "label": "Firefox 34.0"
    },
    "system": {
      "name": "windows7",
      "icon": "windows7",
      "label": "Windows 7"
    }
  },
  "reputation": {
    "threats": [
      "comment_spam",
      "brute_force_login"
    ],
    "status": "bad"
  }
}

Return a Signature object with extra properties:

Properties of the JSON response object

Property Type Description
id string internal identifier
language_code string a language code, extract from the Accept-Language header
country_code string a country code, extract from the Accept-Language header
user_agent object an User Agent object, parsed from the User-Agent header
reputation object a Reputation object

Check the examples on the side.

Identity Combination

Request with IP Address and HTTP Headers:

POST /1.1/identity HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "address": "92.78.176.182",
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate, sdch",
    "Accept-Language": "en-US,en;q=0.8",
    "Cache-Control": "max-age=0",
    "Connection": "keep-alive",
    "DNT": "1",
    "Host": "francois.hodierne.net",
    "Referer": "https://www.google.com/",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
  }
}

curl "https://api.access.watch/1.1/identity" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "92.78.176.182",
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate, sdch",
    "Accept-Language": "en-US,en;q=0.8",
    "Cache-Control": "max-age=0",
    "Connection": "keep-alive",
    "DNT": "1",
    "Host": "francois.hodierne.net",
    "Referer": "https://www.google.com/",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
  }
}'

Request with IP Address and User Agent:

POST /1.1/identity HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "address": "92.78.176.182",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
}

curl "https://api.access.watch/1.1/identity" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "92.78.176.182",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
}'

JSON Response example:

{
  "id": "1244499271eaddd36768ee157403ebe2",
  "type": "browser",
  "address": {
    "id": "e90d9f20cce9c203f439129b0943a8bb",
    "value": "92.78.176.182",
    "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "as_number": "3209",
    "network_name": "ARCOR-DSL-NET17",
    "country_code": "DE",
    "flags": [
      "broadband"
    ]
  },
  "signature": {
    "id": "7ecc3a36d6eae49e535f7a956778a166",
    "language_code": "en",
    "country_code": "US"
  },
  "user_agent": {
    "id": "b516786e573a426eb842ec2132ed35e2",
    "type": "browser",
    "agent": {
      "name": "chrome",
      "icon": "chrome",
      "label": "Chrome 49.0.2623.87"
    },
    "system": {
      "name": "macosx",
      "icon": "macosx",
      "label": "MacOS X 10.11.3"
    }
  },
  "reputation": {
    "threats": [],
    "status": "nice"
  }
}

This endpoint is used to get information about a combination of either:

API Request

POST https://api.access.watch/1.1/identity

This endpoint accept a JSON object as input.

The expected Content-Type is “application/json”.

JSON Input Properties

Parameter Type Required Description
address string yes Ipv4 or Ipv6 address
headers object yes * A collection of HTTP headers
user_agent string yes * A User Agent

Only one of headers or user-agent is required. You should always favor passing headers over user_agent, unless HTTP headers are not available.

API Response

Return an Identity object with extra properties:

Properties of the JSON response object

Property Type Description
id string internal identifier
type string robot or browser, as detected by our platform
address object an Address object
signature object a Signature object (if headers were passed)
user_agent object an User Agent object
reputation object a Reputation object

Session Acquisition

Request with IP Address and HTTP Headers:

POST /1.1/session HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "address": "92.78.176.182",
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate, sdch",
    "Accept-Language": "en-US,en;q=0.8",
    "Cache-Control": "max-age=0",
    "Connection": "keep-alive",
    "DNT": "1",
    "Host": "francois.hodierne.net",
    "Referer": "https://www.google.com/",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
  },
  "session": "e36be9aeff579f81f45d71be06155732"
}

curl "https://api.access.watch/1.1/session" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "92.78.176.182",
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate, sdch",
    "Accept-Language": "en-US,en;q=0.8",
    "Cache-Control": "max-age=0",
    "Connection": "keep-alive",
    "DNT": "1",
    "Host": "francois.hodierne.net",
    "Referer": "https://www.google.com/",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
  },
  "session": "e36be9aeff579f81f45d71be06155732"
}'

JSON Response example:

{
  "session": {
    "id": "e36be9aeff579f81f45d71be06155732",
    "blocked": false
  },
  "identity": {
    "id": "1244499271eaddd36768ee157403ebe2",
    "type": "browser",
    "label": "human",
    "address": {
      "id": "e90d9f20cce9c203f439129b0943a8bb",
      "value": "92.78.176.182",
      "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
      "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
      "as_number": "3209",
      "network_name": "ARCOR-DSL-NET17",
      "country_code": "DE",
      "flags": [
        "broadband"
      ]
    },
    "signature": {
      "id": "7ecc3a36d6eae49e535f7a956778a166",
      "language_code": "en",
      "country_code": "US"
    },
    "user_agent": {
      "id": "b516786e573a426eb842ec2132ed35e2",
      "type": "browser",
      "agent": {
        "name": "chrome",
        "icon": "chrome",
        "label": "Chrome 49"
      },
      "system": {
        "name": "macosx",
        "icon": "macosx",
        "label": "macOS 10.11.3"
      }
    },
    "reputation": {
      "threats": [],
      "status": "nice"
    }
  }
}

This endpoint is used to acquire a session and get information about a combination of either:

It’s usually used in real time before processing the request.

API Request

POST https://api.access.watch/1.1/session

This endpoint accept a JSON object as input.

JSON Input Parameters

Parameter Type Required Description
address string yes Ipv4 or Ipv6 address
headers object yes * A collection of HTTP headers
user_agent string yes * A User Agent
session string no An already existing session id for this agent

Only one of headers or user_agent is required. You should always favor passing headers over user_agent, unless HTTP headers are not available.

API Response

Return a collection of several objects:

Properties of the JSON response object

Property Type Description
identity object an Identity object
session object a Session object

Request Screening

POST /1.1/request HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "address": "92.78.176.182",
  "request": {
    "protocol": "HTTP/1.1",
    "method": "GET",
    "scheme": "http",
    "host": "francois.hodierne.net",
    "port": "80",
    "url": "/resume",
    "headers": {
      "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "Accept-Encoding": "gzip, deflate, sdch",
      "Accept-Language": "en-US,en;q=0.8",
      "Cache-Control": "max-age=0",
      "Connection": "keep-alive",
      "DNT": "1",
      "Host": "francois.hodierne.net",
      "Referer": "https://www.google.com/",
      "Upgrade-Insecure-Requests": "1",
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
    }
  }
}

curl "https://api.access.watch/1.1/request" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "92.78.176.182",
  "request": {
    "protocol": "HTTP/1.1",
    "method": "GET",
    "scheme": "http",
    "host": "francois.hodierne.net",
    "port": "80",
    "url": "/resume",
    "headers": {
      "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "Accept-Encoding": "gzip, deflate, sdch",
      "Accept-Language": "en-US,en;q=0.8",
      "Cache-Control": "max-age=0",
      "Connection": "keep-alive",
      "DNT": "1",
      "Host": "francois.hodierne.net",
      "Referer": "https://www.google.com/",
      "Upgrade-Insecure-Requests": "1",
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
    }
  }
}'

JSON Response example:

{
  "identity": {
    "id": "1244499271eaddd36768ee157403ebe2",
    "type": "browser"
  },
  "address": {
    "id": "e90d9f20cce9c203f439129b0943a8bb",
    "value": "92.78.176.182",
    "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "as_number": "3209",
    "network_name": "ARCOR-DSL-NET17",
    "country_code": "DE",
    "flags": [
        "broadband"
    ]
  },
  "signature": {
    "id": "7ecc3a36d6eae49e535f7a956778a166",
    "language": "en",
    "country": "us"
  },
  "user_agent": {
    "id": "b516786e573a426eb842ec2132ed35e2",
    "type": "browser",
    "agent": {
      "name": "chrome",
      "icon": "chrome",
      "label": "Chrome 49.0.2623.87"
    },
    "system": {
      "name": "macosx",
      "icon": "macosx",
      "label": "MacOS X 10.11.3"
    }
  },
  "reputation": {
    "threats": [],
    "status": "nice"
  }
}

This endpoint is used to get information about an HTTP Request.

It’s usually used in real time to gather knowledge before processing the request.

It can also be used offline to enrich data sets.

API Request

POST https://api.access.watch/1.1/request

This endpoint accept a JSON object as input.

JSON Input Parameters

Parameter Type Required Description
address string yes a valid Ipv4 or Ipv6 address
request object yes a Request object

API Response

Return a collection of several objects:

Properties of the JSON response object

Property Type Description
identity object an Identity object
address object an Address object
signature object a Signature object
user_agent object an User Agent object
reputation object a Reputation object

Request Logging

Single request

POST /1.1/log HTTP/1.1
Host: log.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

{
  "address": "92.78.176.182",
  "request": {
    "protocol": "HTTP/1.1",
    "method": "GET",
    "scheme": "http",
    "host": "francois.hodierne.net",
    "port": "80",
    "url": "/resume",
    "headers": {
      "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "Accept-Encoding": "gzip, deflate, sdch",
      "Accept-Language": "en-US,en;q=0.8",
      "Cache-Control": "max-age=0",
      "Connection": "keep-alive",
      "DNT": "1",
      "Host": "francois.hodierne.net",
      "Referer": "https://www.google.com/",
      "Upgrade-Insecure-Requests": "1",
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
    }
  },
  "response": {
    "status" : "200"
  }
}

curl "https://log.access.watch/1.1/log" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "92.78.176.182",
  "request": {
    "protocol": "HTTP/1.1",
    "method": "GET",
    "scheme": "http",
    "host": "francois.hodierne.net",
    "port": "80",
    "url": "/resume",
    "headers": {
      "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "Accept-Encoding": "gzip, deflate, sdch",
      "Accept-Language": "en-US,en;q=0.8",
      "Cache-Control": "max-age=0",
      "Connection": "keep-alive",
      "DNT": "1",
      "Host": "francois.hodierne.net",
      "Referer": "https://www.google.com/",
      "Upgrade-Insecure-Requests": "1",
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
    }
  },
  "response": {
    "status" : 200
  }
}'

Multiple requests (batch)

POST /1.1/log HTTP/1.1
Host: log.access.watch
Api-Key: <Api_Key>
Accept: application/json
Content-Type: application/json

[
  {
    "address": "92.78.176.182",
    "request": {
      "protocol": "HTTP/1.1",
      "method": "GET",
      "scheme": "http",
      "host": "francois.hodierne.net",
      "port": "80",
      "url": "/",
      "headers": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "Accept-Encoding": "gzip, deflate, sdch",
        "Accept-Language": "en-US,en;q=0.8",
        "Cache-Control": "max-age=0",
        "Connection": "keep-alive",
        "DNT": "1",
        "Host": "francois.hodierne.net",
        "Referer": "https://www.google.com/",
        "Upgrade-Insecure-Requests": "1",
        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
      }
    },
    "response": {
      "status" : "200"
    }
  },
  {
    "address": "92.78.176.182",
    "request": {
      "protocol": "HTTP/1.1",
      "method": "GET",
      "scheme": "http",
      "host": "francois.hodierne.net",
      "port": "80",
      "url": "/",
      "headers": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "Accept-Encoding": "gzip, deflate, sdch",
        "Accept-Language": "en-US,en;q=0.8",
        "Cache-Control": "max-age=0",
        "Connection": "keep-alive",
        "DNT": "1",
        "Host": "francois.hodierne.net",
        "Upgrade-Insecure-Requests": "1",
        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
      }
    },
    "response": {
      "status" : "200"
    }
  }
]

curl "https://log.access.watch/1.1/log" \
  -H "Api-Key: <Api_Key>" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "address": "92.78.176.182",
    "request": {
      "protocol": "HTTP/1.1",
      "method": "GET",
      "scheme": "http",
      "host": "francois.hodierne.net",
      "port": "80",
      "url": "/resume",
      "headers": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "Accept-Encoding": "gzip, deflate, sdch",
        "Accept-Language": "en-US,en;q=0.8",
        "Cache-Control": "max-age=0",
        "Connection": "keep-alive",
        "DNT": "1",
        "Host": "francois.hodierne.net",
        "Referer": "https://www.google.com/",
        "Upgrade-Insecure-Requests": "1",
        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
      }
    },
    "response": {
      "status" : 200
    }
  },
  {
    "address": "92.78.176.182",
    "request": {
      "protocol": "HTTP/1.1",
      "method": "GET",
      "scheme": "http",
      "host": "francois.hodierne.net",
      "port": "80",
      "url": "/",
      "headers": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "Accept-Encoding": "gzip, deflate, sdch",
        "Accept-Language": "en-US,en;q=0.8",
        "Cache-Control": "max-age=0",
        "Connection": "keep-alive",
        "DNT": "1",
        "Host": "francois.hodierne.net",
        "Upgrade-Insecure-Requests": "1",
        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
      }
    },
    "response": {
      "status" : "200"
    }
  }
]'

JSON Response example:

{
  "message": "Ok"
}

This endpoint is used to log and index an HTTP request.

API Request

POST https://log.access.watch/1.1/log

Single request

This endpoint accept a JSON object as input.

Multiple requests (batch)

This endpoint also accept a collection of JSON objects as input.

JSON Input Parameters

Parameter Type Description
time string Date & Time in ISO8601 format
address string a valid Ipv4 or Ipv6 address
request object a Request object
response object a Response object

API Response

The request is processed asynchronously and there is nothing to expect in the response.

Retrieving Logs

POST /1.1/logs?limit=1 HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json

curl "https://api.access.watch/1.1/logs?limit=1" \
  -H "Api-Key: <Api_Key>"

JSON Response example:

{
  "logs": [
    {
      "request": {
        "protocol": "HTTP\/1.1",
        "method": "GET",
        "scheme": "http",
        "host": "francois.hodierne.net",
        "port": "80",
        "url": "\/resume",
        "headers": {
          "accept": "text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,*\/*;q=0.8",
          "accept-encoding": "gzip, deflate, sdch",
          "accept-language": "en-US,en;q=0.8",
          "cache-control": "max-age=0",
          "connection": "keep-alive",
          "dnt": "1",
          "host": "francois.hodierne.net",
          "referer": "https:\/\/www.google.com\/",
          "upgrade-insecure-requests": "1",
          "user-agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/49.0.2623.87 Safari\/537.36"
        }
      },
      "response": {
        "status": 200
      },
      "identity": {
        "id": "1244499271eaddd36768ee157403ebe2",
        "type": "browser"
      },
      "address": {
        "id": "e90d9f20cce9c203f439129b0943a8bb",
        "value": "92.78.176.182",
        "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
        "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
        "as_number": "3209",
        "network_name": "ARCOR-DSL-NET17",
        "country_code": "DE",
        "flags": [
          "broadband"
        ]
      },
      "signature": {
        "id": "7ecc3a36d6eae49e535f7a956778a166",
        "language_code": "en",
        "country_code": "US"
      },
      "user_agent": {
        "id": "b516786e573a426eb842ec2132ed35e2",
        "type": "browser",
        "agent": {
          "name": "chrome",
          "icon": "chrome",
          "label": "Chrome 49.0.2623.87"
        },
        "system": {
          "name": "macosx",
          "icon": "macosx",
          "label": "MacOS X 10.11.3"
        }
      },
      "reputation": {
        "threats": [],
        "status": "nice"
      }
    }
  ]
}

This endpoint is used to retrieve logs.

API Request

GET https://api.access.watch/1.1/logs

URL Parameters

Parameter Type Description
q string full text search
limit int the maximum number of logs in the response
after string all logs after the Date & Time in ISO8601 format
before string all logs before the Date & Time in ISO8601 format
session string filter logs by session id

API Response

Properties of the JSON response object

Parameter Type Description
logs array an array of Log objects

Retrieving Sessions

POST /1.1/sessions?limit=1 HTTP/1.1
Host: api.access.watch
Api-Key: <Api_Key>
Accept: application/json

curl "https://api.access.watch/1.1/sessions?limit=1" \
  -H "Api-Key: <Api_Key>"

JSON Response example:

{
  "sessions": [
    {
      "id": "8efe0f2ac4767f4e1131f4d6a5186767",
      "count": 137,
      "identity": {
        "id": "1244499271eaddd36768ee157403ebe2",
        "type": "browser"
      },
      "address": {
        "id": "e90d9f20cce9c203f439129b0943a8bb",
        "value": "92.78.176.182",
        "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
        "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
        "as_number": "3209",
        "network_name": "ARCOR-DSL-NET17",
        "country_code": "DE",
        "flags": [
          "broadband"
        ]
      },
      "signature": {
        "id": "7ecc3a36d6eae49e535f7a956778a166",
        "language_code": "en",
        "country_code": "US"
      },
      "user_agent": {
        "id": "b516786e573a426eb842ec2132ed35e2",
        "type": "browser",
        "agent": {
          "name": "chrome",
          "version": "49.0.2623.87",
          "icon": "chrome",
          "label": "Chrome 49.0.2623.87"
        },
        "system": {
          "name": "macosx",
          "icon": "macosx",
          "label": "MacOS X 10.11.3"
        }
      },
      "reputation": {
        "threats": [],
        "status": "nice"
      }
    }
  ]
}

This endpoint is used to retrieve sessions.

API Request

GET https://api.access.watch/1.1/sessions

URL Parameters

Parameter Type Description
limit int the maximum number of entries in the response

API Response

Properties of the JSON response object

Parameter Type Description
sessions array a collection of Session objects with extra properties

Properties of the JSON objects in the collection

Parameter Type Required Description
id string y an internal session identifier
count int y number of requests
updated string y last Date & Time of activity, ISO8601 format
identity object y an Identity Combination object
address object y an IP Address object
signature object n a Signature object
user_agent object n a User Agent object
speed object n a Speed object
reputation object y a Reputation object

Objects

IP Address object

Sample Address object

{
  "id": "e90d9f20cce9c203f439129b0943a8bb",
  "value": "92.78.176.182",
  "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
  "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
  "as_number": "3209",
  "network_name": "ARCOR-DSL-NET17",
  "country_code": "DE",
  "flags": [
    "broadband",
  ]
}

Properties of an Address object

Parameter Type Description
id string internal identifier
value string the ipv4 or ipv6 address
hostname string the reverse hostname for the address
label string a human label for the address (currently hostname or value)
as_number string the autonomous system number
network_name string the network name
country_code string the country code, two letter (ISO 3166-1 alpha-2)
flags array see flags section

Flags for an Address object

Flag Description
broadband IP from a broadband connection (cable, dsl)
mobile IP from a mobile connection (GSM, GPRS, 3G, LTS)
server IP from a server in a data center
business IP from a business broadband connection
corporate IP from the network of a big corporation
institution IP from a public institution (federal, national, local)
education IP from an education institution (university, school)
wifi IP from a commercial Wifi provider
wimax IP from a commercial Wimax provider
sat IP from a satellite provider
vpn IP from a VPN provider
proxy IP from a commercial proxy (like Opera Mini or Google)
cloud IP from a cloud server like AWS or Google Cloud
tor IP used a a Tor exit
crawler IP from a known crawler
robot IP used by robot agent

User Agent object

Sample User Agent object

{
  "id": "a46c391e4a75e4a3734042b6077e8cfc",
  "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36",
  "type": "browser",
  "agent": {
    "name": "chrome",
    "icon": "chrome",
    "version": "49.0.2623.87",
    "label": "Chrome 49"
  },
  "system": {
    "name": "macosx",
    "icon": "macosx",
    "version": "10.11.3",
    "label": "OS X 10.11"
  }
}

Properties of a User Agent object

Parameter Type Description
id string internal identifier
value string the text value
type string browser or robot, detected from the value
agent object with name, icon, version and label as properties
system object with name, icon, version and label as properties

Headers Signature object

Sample Headers Signature object:

{
  "id": "7ecc3a36d6eae49e535f7a956778a166",
  "language_code": "en",
  "country_code": "us"
}

Properties of an Headers Signature object

Parameter Type Required Description
id string yes internal identifier
language_code string no a language code, parsed from the Accept-Language header
country_code string no a country code, parsed from the Accept-Language header

Identity Combination object

Sample Identity Combination object:

{
  "id": "07051caab3d3d1e3a72bf9d635601080",
  "type": "robot",
  "name": "Google",
  "label": "verified robot",
  "description": "Agent operating from a verified IP address."
}

Properties of an Identity Combination object

Parameter Type Description
id string internal unique identifier
type string robot or browser, as detected by our platform, can be null
name string name of the identity
label string label for the identity
description string description of the identity

Request object

Sample Request object:

{
  "protocol": "HTTP/1.1",
  "method": "GET",
  "scheme": "http",
  "host": "francois.hodierne.net",
  "port": "80",
  "url": "/resume",
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate, sdch",
    "Accept-Language": "en-US,en;q=0.8",
    "Cache-Control": "max-age=0",
    "Connection": "keep-alive",
    "DNT": "1",
    "Host": "francois.hodierne.net",
    "Referer": "https://www.google.com/",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
  }
}

Properties of a Request object

Parameter Type Required Description
protocol string no HTTP/1.0, HTTP/1.1 or HTTP/2.
method string yes HTTP Method: HEAD, GET, POST, …
scheme string yes http or https
host string yes the host for the request
port int no default to 80/443 (http/https)
url string yes The relative URL (path + query string)
user_agent string yes * a User Agent string
headers object yes * a collection of HTTP headers

Only one of headers or user_agent is required. headers should always be favored over user_agent, unless HTTP headers are not available.

Response object

Sample Response object:

{
  "status": "200"
}

This object is Work in Progress, more properties will be added as soon as they are supported.

Properties of a Response object

Parameter Type Required Description
status string yes the HTTP status code for the response

Reputation object

Sample Reputation object:

{
  "status": "bad",
  "threats": [
    "suspicious_scan",
    "comment_spam",
    "brute_force_login"
  ]
}

Properties of a Reputation object

Parameter Type Description
status string see statuses section
threats array see threats section

Statuses for a Reputation object

Status Description
nice perfect, as far as we know you can trust this entity
ok all right, so far no reason to worry about this entity
suspicious warning, nothing really bad, but the entity is on our radar
bad danger, there is good reasons to watch or block this entity

Threats for a Reputation object

Value Description
suspicious_scan used to scan websites for known software and security holes
comment_spam used to post comment spam
referer_spam used for referer spam
brute_force_login used for brute force attacks against login forms

Log object

Sample Log object:

{
  "id": "AVTEO6wYz61cviQDplR3",
  "time": "2016-05-18T16:00:35+02:00",
  "request": {
    "protocol": "HTTP\/1.1",
    "method": "GET",
    "scheme": "http",
    "host": "francois.hodierne.net",
    "port": "80",
    "url": "\/resume",
    "headers": {
      "accept": "text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,*\/*;q=0.8",
      "accept-encoding": "gzip, deflate, sdch",
      "accept-language": "en-US,en;q=0.8",
      "cache-control": "max-age=0",
      "connection": "keep-alive",
      "dnt": "1",
      "host": "francois.hodierne.net",
      "referer": "https:\/\/www.google.com\/",
      "upgrade-insecure-requests": "1",
      "user-agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/49.0.2623.87 Safari\/537.36"
    }
  },
  "response": {
    "status": 200
  },
  "identity": {
    "id": "1244499271eaddd36768ee157403ebe2",
    "type": "browser"
  },
  "address": {
    "id": "e90d9f20cce9c203f439129b0943a8bb",
    "value": "92.78.176.182",
    "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "as_number": "3209",
    "network_name": "ARCOR-DSL-NET17",
    "country_code": "DE",
    "flags": [
      "broadband"
    ]
  },
  "signature": {
    "id": "7ecc3a36d6eae49e535f7a956778a166",
    "language_code": "en",
    "country_code": "US"
  },
  "user_agent": {
    "id": "b516786e573a426eb842ec2132ed35e2",
    "type": "browser",
    "agent": {
      "name": "chrome",
      "icon": "chrome",
      "label": "Chrome 49.0.2623.87"
    },
    "system": {
      "name": "macosx",
      "icon": "macosx",
      "label": "MacOS X 10.11.3"
    }
  },
  "reputation": {
    "threats": [],
    "status": "nice"
  }
}

Properties of a Log object

Parameter Type Required Description
id string yes internal identifier
time string yes Date & Time in ISO8601 format
request object yes a Request object
response object yes a Response object
identity object yes an Identity Combination object
address object yes an IP Address object
signature object yes a Signature object
user_agent object no a User Agent object
robot object no a Robot object
reputation object yes a Reputation object

Session object

Sample Session object:

{
  "id": "8efe0f2ac4767f4e1131f4d6a5186767",
  "count": 137,
  "identity": {
    "id": "1244499271eaddd36768ee157403ebe2",
    "type": "browser"
  },
  "address": {
    "id": "e90d9f20cce9c203f439129b0943a8bb",
    "value": "92.78.176.182",
    "hostname": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "label": "dslb-092-078-176-182.092.078.pools.vodafone-ip.de",
    "as_number": "3209",
    "network_name": "ARCOR-DSL-NET17",
    "country_code": "DE",
    "flags": [
      "broadband"
    ]
  },
  "signature": {
    "id": "7ecc3a36d6eae49e535f7a956778a166",
    "language_code": "en",
    "country_code": "US"
  },
  "user_agent": {
    "id": "b516786e573a426eb842ec2132ed35e2",
    "type": "browser",
    "agent": {
      "name": "chrome",
      "icon": "chrome",
      "label": "Chrome 49.0.2623.87"
    },
    "system": {
      "name": "macosx",
      "icon": "macosx",
      "label": "MacOS X 10.11.3"
    }
  },
  "reputation": {
    "threats": [],
    "status": "nice"
  }
}

Properties of a Session object

Parameter Type Required Description
id string yes an internal session identifier
count int no a number of requests
identity object yes an Identity Combination object
address object yes an IP Address object
signature object no a Signature object
user_agent object no a User Agent object
robot object no a Robot object
speed object no a Speed object
reputation object yes a Reputation object

Speed object

Sample Speed object:

{
  "interval": 42.704637333303,
  "per_second": 0.02,
  "per_minute": 1.4
}

Properties of a Speed object

Parameter Type Required Description
interval float yes the interval between 2 events, in seconds
per_second float yes the number of events per second
per_minute float yes the number of events per minute

Robot object

Sample Robot object:

{
  "id": "dcbe4598-3144-4085-b886-80c7d4b31bdd",
  "name": "Google",
  "label": "Crawler",
  "description": "Google is an internet company operating a famous search engine and many other services.",
  "url": "https:\/\/access.watch\/database\/robots\/nice\/google",
  "icon": "https:\/\/api.access.watch\/1.1\/icon\/robot\/dcbe4598-3144-4085-b886-80c7d4b31bdd",
  "flags": [
    "crawler"
  ]
}

Properties of a Robot object

Parameter Type Description
id string a unique identifier
name string name of the robot for humans
label string short description of the purpose and/or reputation
description string description of the robot, its purpose
url string url of the robot entry in the Access Watch database
icon string url of an svg icon representing the robot
flags array see flags section

Flags for a Robot object

Flag Description
crawler crawling and indexing the web
rss fetching RSS feeds
monitoring checking website uptime and performance
security checking website security
seo crawling data for SEO analysis
social checking links from social networks
advertising linked to advertising technology
tor using principally the Tor network

Errors

The Access Watch API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
HTTP cURL