Skip to main content
API docs by Redocly

MediaGuard API (1.0)

Download OpenAPI specification:Download

The MediaGuard HTTP API lets you send pre-bid data to HUMAN and receive IVT predictions accordingly. The MediaGuard HTTP service mirrors the core features of the gRPC service and lets you use any HTTP client to access the MediaGuard API.

Authentication

The MediaGuard API requires request-level authentication using basic HTTP 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 query the MediaGuard HTTP 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.

Endpoints

The MediaGuard API includes two endpoints: one to perform a lookup request, and one to check the status of MediaGuard's servers.

Perform a lookup request

Sends details about a specific bid request to MediaGuard, then returns HUMAN's analysis of whether the bid request is a form of invalid traffic (IVT).

Request Body schema: application/json
ip
required
string

The IP address of the device where the ad impression (and HUMAN's detection tag) is intended to be delivered. This parameter expects the raw byte representation of the input address and accepts both IPv4 and IPv6 addresses.

userAgent
required
string

The user agent of the user who drove the bid request.

url
required
string

The full URL of the site of the bid request.

Note that you must include either the url or appID parameter with each lookup request, but do not need to include both.

referer
string

The full URL of the page that referred the user to the site of the event. This parameter follows the same formatting as the url parameter.

This parameter is exclusive to Desktop Web and Mobile Web environments. If a bid request originated from one of these environments, you must include the referer parameter in that bid's lookup request.

appId
string

The app bundle where the ad is intended to be delivered (for bid requests in Mobile App and CTV environments only). This parameter expects a valid string and should reflect OpenRTB bundle standards (i.e., Android bundles are package names, while iOS bundles are usually numerical IDs).

Note that you must include either the url or appID parameter with each lookup request, but do not need to include both.

userId
string

A unique identifier that HUMAN uses to identify the user driving each event.

For events in mobile environments, you should set this parameter's value to the device's iOS IDFA or Android AAID (when possible); for all other environments, you should generate a unique identifier that persists across all of that user's events until that user's cookies are cleared.

impressionId
string

A unique identifier that HUMAN uses to identify each event. You can set this parameter's value to the auction ID or impression ID for that event's bid request. This parameter is optional and helps us perform additional troubleshooting as needed.

supplyChainObject
string

A string-encoded representation of the OpenRTB supplyChainObject for that event's bid request.

required
object
object

Responses

Request samples

Content type
application/json
{
  • "ip": "127.127.127.5",
  • "userAgent": "Mozilla/5.0 (iPad; CPU OS 10_2 like Mac OS X)",
  • "url": "example.com/full/url/detail.html",
  • "referer": "sub.example.com/source",
  • "appId": "553834731",
  • "userId": "c3f927f4-3ef9-4b53-8887-d794c4daea82",
  • "impressionId": "a67e10e8-df61-44ef-b3bc-9a600e23e538",
  • "supplyChainObject": "1.0,1!exchange1.com,1234,1,bid-request-1,publisher,publisher.com",
  • "sortBy": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "lookupId": "561356d9-b92f-4281-ba3a-7bc0448f066d",
  • "ivt": true,
  • "serverId": "test-vm-1",
  • "ivtTaxonomy": [
    ]
}

Check MediaGuard's status

Queries the status of the MediaGuard server.

Note that this endpoint always returns an empty response body; you should use the HTTP response code to determine the server's current status.

Responses