openapi: 3.0.3
info:
  title: MediaGuard API
  description: >-
    The MediaGuard API lets you send pre-bid data to HUMAN and receive IVT
    predictions accordingly. This HTTP-based API mirrors the core features of
    our gRPC-based SDK.


    The MediaGuard API includes two endpoints:


    * The default `/lookup` endpoint expects individual details about a bid
    request (extracted from an OpenRTB `BidRequest` object) in its request body.
    MediaGuard analyzes these details and returns an IVT prediction.

    * The `/health-check` endpoint checks the status of MediaGuard's servers.


    ## Authentication


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


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


    ## Using curl


    You can use curl to access the MediaGuard API. For example, the following
    command shows how to query the `/ookup` endpoint using curl and basic HTTP
    authentication:


    ```

    curl --location --request POST '/lookup' \

    --header 'Authorization: Basic <base64(username:password)>' \

    --header 'Content-Type: application/json' \

    --header 'Content-Encoding: gzip' \

    --header 'Accept-Encoding: gzip' \

    --data-raw '{
        "ip": {...},
        "userAgent": {...},
        "url": {...}
    }'

    ```
servers:
  - url: https://<YOUR-MEDIAGUARD-SERVER-URL>
paths:
  /lookup:
    post:
      summary: Perform a lookup request
      description: >-
        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).


        ### Content type

        The `/lookup` endpoint supports body encoding in both JSON and protobuf.
        You can use the `Content-Type` header to specify which type you're
        using.
      parameters:
        - in: header
          example: application/json
          name: Content-Type
          schema:
            type: string
          required: false
          description: >-
            Specifies the body encoding for your lookup request; possible values
            are `application/json` and `application/protobuf`. If no type is
            specified, MediaGuard will expect JSON encoding by default.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
      responses:
        '200':
          description: >-
            Successful lookup request that returns HUMAN's “bot or not”
            decision:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupResponse'
        '400':
          description: Invalid argument provided.
  /health-check:
    get:
      summary: Check MediaGuard's status
      description: >-
        Queries the current status of MediaGuard.


        Note that this endpoint always returns an empty response body; you
        should use the HTTP response code to determine MediaGuard's current
        status.
      responses:
        '200':
          description: MediaGuard is ready to receive requests.
        '503':
          description: MediaGuard is unavailable to receive requests.
components:
  schemas:
    ORTBLookupRequest:
      type: object
      required:
        - ortb
        - metadata
      example:
        ortb:
          id: 80ce30c53c16e6ede735f123ef6e32361bfc7b22
          at: 2
          imp:
            - id: '1'
              bidfloor: 0.5
              banner:
                h: 728
                w: 90
                pos: 1
          app:
            id: agltb3B1Yi1pbmNyDAsSA0FwcBiJkfIUDA
            name: Yahoo Weather
            ver: 1.0.2
            bundle: '12345'
            storeurl: https://itunes.apple.com/id628677149
            publisher:
              id: agltb3B1Yi1pbmNyDAsSA0FwcBiJkfTUCV
              name: yahoo
              domain: www.yahoo.com
          device:
            ua: >-
              Mozilla/5.0 (iPhone; CPU iPhone OS 16_6 like Mac OS X)
              AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148
            ip: 127.0.0.1
            devicetype: 4
            ifa: c3f927f4-3ef9-4b53-8887-d794c4daea82
          source:
            schain:
              ver: '1.0'
              complete: 1
              nodes:
                - asi: rubiconproject.com
                  sid: acltb3B1Yi2pbxNyDAsSA0FwcBiJkfLUCV
                  hp: 1
        metadata:
          __supplier_id__: rubiconproject.com
          __ortb_version__: v2.6-202303
          meta-2: data-2
          meta-1: data-1
      properties:
        ortb:
          type: object
          description: >-
            The OpenRTB `BidRequest` object associated with the bid request that
            you'd like MediaGuard to analyze.
        metadata:
          type: object
          required:
            - __supplier_id__
            - __ortb_version__
          description: >-
            An object that contains additional key/value pairs with information
            to send to MediaGuard, including custom metadata. (Custom metadata
            is optional; however, the `metadata` object itself is not optional,
            since it contains the `__supplier_id__` and `__ortb_version__`
            fields, which are both required.)
          properties:
            __supplier_id__:
              type: string
              description: >-
                The current seller of the ad inventory. This value must be
                consistent with OpenRTB’s Publisher ID and should match the
                value in the second field of the ads.txt file. If you are a
                supply-side platform (SSP), this is usually your own domain.
            __ortb_version__:
              type: string
              description: >-
                The OpenRTB version of the `BidRequest` object that you're
                sending to MediaGuard. This must be a value in the format of
                `v2.5-xxxxxx` or `v2.6-xxxxxx` (for example, `v2.6-202303`).
            <custom>:
              type: string
              description: Any custom metadata you'd like to send to MediaGuard.
    LookupRequest:
      type: object
      required:
        - ip
        - userAgent
        - url
        - sortBy
      properties:
        ip:
          type: string
          example: 127.127.127.5
          description: >-
            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:
          type: string
          example: Mozilla/5.0 (iPad; CPU OS 10_2 like Mac OS X)
          description: 'The user agent of the user who drove the bid request. '
        url:
          type: string
          example: example.com/full/url/detail.html
          description: >-
            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:
          type: string
          example: sub.example.com/source
          description: >-
            The full URL of the page that referred the user to the site of the
            bid request. 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:
          type: string
          example: '553834731'
          description: >-
            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:
          type: string
          example: c3f927f4-3ef9-4b53-8887-d794c4daea82
          description: >-
            A unique identifier that HUMAN uses to identify the user driving
            each bid request.


            For bid request 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 bid request until
            that user's cookies are cleared.
        impressionId:
          type: string
          example: a67e10e8-df61-44ef-b3bc-9a600e23e538
          description: >-
            A unique identifier that HUMAN uses to identify each bid request.
            You can set this parameter's value to the auction ID or impression
            ID for that bid request. This parameter is optional and helps us
            perform additional troubleshooting as needed.
        supplyChainObject:
          type: string
          example: 1.0,1!exchange1.com,1234,1,bid-request-1,publisher,publisher.com
          description: >-
            A string-encoded representation of the bid request's OpenRTB
            `supplyChainObject`.
        inventoryPartnerDomain:
          type: string
          example: partnerdomain.com
          description: >-
            The domain of the authorized partner who owns the inventory that
            corresponds to the bid request. This value should match either the
            [`app.inventorypartnerdomain`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3214---object-app-)
            or
            [`site.inventorypartnerdomain`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3213---object-site-)
            field in the [OpenRTB `BidRequest`
            object](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#321---object-bidrequest-).


            You should only include this parameter if the inventory is owned by
            an authorized partner (rather than the publisher themselves).
        sortBy:
          type: object
          description: >-
            An object that contains additional information that HUMAN uses to
            categorize and sort bid request data.
          required:
            - supplierId
            - publisherId
          properties:
            supplierId:
              type: string
              example: '12345'
              description: >-
                The domain of the ad system that created the current version of
                the bid request. This value should match the first field of the
                associated entry in the publisher’s ads.txt or app-ads.txt file.
                If you are a supply-side platform (SSP), this is usually your
                own domain.
            publisherId:
              type: string
              example: '787656'
              description: >-
                The ID of the publisher account associated with the supply
                source for that bid request. Corresponds to the OpenRTB
                `Publisher` object. 
            mediaType:
              type: string
              example: '2'
              description: >-
                The media type of the ad inventory (display, video, SSAI,
                *etc.*).
            deviceType:
              type: string
              example: '4'
              description: >-
                The device type where the bid request occurred (desktop, tablet,
                phone, *etc.*).
        metadata:
          type: object
          description: >-
            An object that contains additional information to send to
            MediaGuard.
          properties:
            example-key:
              type: string
              example: example value
              description: >-
                Any custom metadata (in the form of key/value pairs) that you'd
                like to include in each lookup request. As part of your
                MediaGuard integration, we may recommend that you send this
                extra data to HUMAN's servers for enhanced reporting data and
                easier troubleshooting.
    LookupResponse:
      type: object
      properties:
        lookupId:
          type: string
          example: 561356d9-b92f-4281-ba3a-7bc0448f066d
          description: >-
            The unique MediaGuard Prediction ID that corresponds to your lookup
            request.<p>

            If you're using the protobuf content type, keep in mind that the
            byte array representation of `lookupId` that's returned in the
            protobuf object/spec assumes little endian formatting. Some language
            methods (like .NET) use parsing methods that assume big endian
            formatting; however, you **must** use a parsing method that assumes
            little endian formatting.
        ivt:
          type: boolean
          example: true
          description: >-
            A Boolean value that, when true, indicates that HUMAN has identified
            the bid request as invalid traffic (IVT).
        serverId:
          type: string
          example: test-vm-1
          description: The ID of the MediaGuard server that received your lookup request.
        ivtTaxonomy:
          type: array
          description: >-
            A list of IVT categories associated with the bid request. Can
            contain one or multiple values.
          items:
            type: string
          example:
            - AB-BOT
            - FR-EMU_RUD
    ORTBLookupResponse:
      type: object
      properties:
        id:
          type: string
          example: 80ce30c53c16e6ede735f123ef6e32361bfc7b22
          description: >-
            The ID of the OpenRTB `BidRequest` object that you sent to
            MediaGuard.
        lookupId:
          type: string
          example: b5f684df-f81e-9dd9-0102-b2f2d9a67ddc
          description: >-
            The unique MediaGuard Prediction ID that corresponds to your lookup
            request.
        ivt:
          type: boolean
          example: true
          description: >-
            A Boolean value that, when true, indicates that HUMAN has identified
            the bid request as invalid traffic (IVT).
        serverId:
          type: string
          example: test-vm-1
          description: The ID of the MediaGuard server that received your lookup request.
        ivtTaxonomy:
          type: array
          description: >-
            A list of IVT categories associated with the bid request. Can
            contain one or multiple values.
          items:
            type: string
          example:
            - AB-BOT
            - FR-EMU_RUD
        system:
          type: object
          description: >-
            This object contains metadata that HUMAN uses for internal debugging
            purposes. You can safely ignore this.
        features:
          type: object
          description: >-
            This object contains supplemental information about your lookup
            request.
          properties:
            result:
              type: string
              example: deny
              description: >-
                An additional response returned by MediaGuard. By default, this
                value is set to `deny` for any bid requests where `"ivt": true`,
                and `allow` for any bid requests where `"ivt": false`.
  securitySchemes:
    humanAuth:
      type: http
      scheme: basic
      description: >-
        To authenticate a request, provide an `Authorization` header with the
        value `Basic base64(username:password)`. For example, if your HUMAN Auth
        ID is `whiteops` and your HUMAN Auth Key is `secret`, your
        `Authorization` header should be set to `Basic d2hpdGVvcHM6c2VjcmV0`.
security:
  - humanAuth: []
