MediaGuard API

The MediaGuard API provides the endpoints you can use to assess ad impressions for fraud.


The MediaGuard API requires request-level authentication using HTTP basic authentication. To authenticate a request, provide an Authorization header on your requests with the value Basic base64(username:password).  

For example, if your HUMAN Auth ID is whiteops and your Auth Key is secret, your Authorization header should be set to Basic d2hpdGVvcHM6c2VjcmV0.

Using cURL

You can use cURL to access the MediaGuard API. The following command illustrates how to hit the MediaGuard API using cURL and basic HTTP authentication.

curl -u "username:password" -i https://example.<domain>.com/endpoint

Content type (JSON and Protocol Buffers)

All MediaGuard API endpoints support body encoding in both JSON and Protocol Buffers (protobuf). To choose between these content types, set the Content-Type header to either application/json or application/protobuf as needed. If no type is specified, JSON is used by default.


The following endpoints are available through the MediaGuard API.

Lookup request

Perform a lookup for the provided bid request details, which returns HUMAN's response of whether or not the bid request is a form of invalid traffic (IVT).

URL: /lookup

Method: POST

Success Response

Code: 200 OK


Content example: After performing the lookup request, HUMAN returned a “bot or not” decision:


    "lookupId": "81d6f-a1b47e-44ed4768",

    "ivt": true,

    "serverId": "dev-vm",

    "ivtTaxonomy": [

      "<ivt code>"



Use the LookupResponse protobuf object. For details on implementing this object, please contact a HUMAN representative for access to our protobuf specification.

Error Response

Condition: Invalid argument provided.


Content example: 

error processing lookup: rpc error: code = InvalidArgument desc = Invalid request

Health request

Queries the health of the MediaGuard server.

URL: /health-check

Method: GET

Success Response

Code: 200 OK

Description: The MediaGuard server is ready to serve requests.

Error response

Code: 503 Service Unavailable 

Description: The MediaGuard server is unavailable to server requests.