NAV Navbar
cURL JavaScript Python Ruby
  • Pavlov Training Manual
  • Core Concepts
  • Workflow: Image Moderation
  • Workflow: Account Security
  • Pavlov Training Manual

    Adjust the language above to change the example code. Documentation appears on the center panel, while examples appear on the right panel in the selected language.

    Welcome to the Pavlov API. 🐶

    Pavlov provides integrated, extensible risk workflows for modern businesses. We provide the tools necessary to stop bad actors, protect your customers, and mitigate risk on an on-going basis. Want to understand how Pavlov works? Learn about the core concepts.

    The Pavlov API requires an auth token to get started. Don't have an auth token? Request Early Access »

    You can access the Pavlov API programmatically using your HTTP client of choice. Requests to our HTTP API are secure and transferred over HTTPS. Response bodies are encoded using JSON.

    Core Concepts

    Workflows

    Workflows are step-wise processes that encodes operational business logic. Workflows unify the intelligence of machine learning models and decisions made by human analysts via the Pavlov Console interface.

    Workflows are run against targets (i.e. actors, images) in Pavlov's entity graph. A workflow may apply annotations to these targets such as labels and scores. These annotations will change over time as actors interact with your website and analysts override automatecd decisions. A target's annotation describes the current state of the target in a workflow, such as whether or not it has been approved or denied.

    Common labels include:

    The score annotation is a number between 0 and 1, demonstrating Pavlov’s confidence in the decision (1 being full confidence). Reasons are an array of strings, providing human-readable descriptions for why the annotation was made.

    Running workflows

    Example: Run a workflow by making a POST request to its run URL.

    POST https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    

    The response will be JSON formatted and contain the target’s unique identifier:

    {
      "id": "TRGXXXXXXXXXXXXXXXXXXXXXX"
    }
    

    You run workflows via an HTTP request. In this request, supply the target of the run, for example the image that you wish to moderate. Different workflows will have different requirements for the targets they are run against. Targets will appear in the Pavlov Console, and the results can be validated server-side. The results of the workflow will be invisible to your users, and can be received by your server asynchronously.

    You can find your workflow’s Run URL in the Pavlov Console. One is available for production, and another for staging so you can test worklows in isolation. This endpoint has CORS enabled, so you will be able to make the HTTP call directly from your web front-end. To run the workflow, make an HTTP POST request to the workflow’s run URL.

    Your front end should send the target identifier to your back end for cross referencing when receiving updates.

    Receiving updates

    {
      "data": {
        "target": {
          "...": "..."
        }
      }
    

    Whenever a target's label, score, or reasons change, Pavlov makes a web request to a URL exposed on by your server with the updated target information. The webhook request body will include the data determined by the workflow. You can change the webhook endpoint where you receive requests via the workflow settings page.

    For security reasons, please verify that requests made to your update webhook URL originate from Pavlov using the update webhook secret found in the workflow's settings. All requests from Pavlov will include the Pavlov-Webhook-Secret header with this secret, and your server should reject all requests without it.

    Actors

    Actors are Pavlov's abstraction of users on your website or application. An actor may be resolvable to a specific person, or may not be. Regardless, Pavlov can run workflows against both known and anonymous actors.

    Actors may be identified by a number of fields:

    Workflow: Image Moderation

    Example: Assess the risk of an image by uploading it.

    curl "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
      -F image=@path/to/image.png
    
    // using isomorphic-fetch
    // https://github.com/matthew-andrews/isomorphic-fetch
    
    import 'isomorphic-fetch'
    import fs from 'fs'
    
    const runURL =
      "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    const form = new FormData();
    form.append('image', image, 'image.png');
    
    fetch(runURL, { method: 'POST', body: form })
      .then(res => res.json())
      .then(resBody => {
        console.log(resBody.id)
      })
      .catch(err => console.error(err));
    
    # using requests
    # http://docs.python-requests.org/en/master/
    
    import requests
    
    run_url = "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    image = open('/path/to/image.png', 'rb')
    res = requests.post(run_url, files={'image': image})
    print(res.json()['id'])
    
    # using rest-client
    # https://github.com/rest-client/rest-client
    
    require "json"
    require "rest-client"
    
    run_url = "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    res = RestClient.post(run_url, image: File.new('/path/to/file'))
    id = JSON.parse(res.body)
    puts id
    

    The response will be JSON formatted and contain the target’s unique identifier.

    {
      "id": "TRGXXXXXXXXXXXXXXXXXXXXXX"
    }
    

    Asynchronous updates to targets will be sent to your update webhook URL.

    {
      "data": {
        "target": {
          "id": "TRGXXXXXXXXXXXXXXXXXXXXXX",
          "label": "DENY",
          "score": 1.0,
          "reasons": ["may contain a hate symbol"],
          "updatedAt": "2017-11-02T21:24:56.224Z",
          "image": {
            "rawURL": "...",
            "sha256": "..."
          }
        }
      }
    }
    

    Image Moderation Workflow Diagram

    Moderate an image for problematic content. Pavlov will keep track of your decisions for images and will moderate similar-looking images according to your feedback.

    Our automation system will detect many common forms of problematic content, including hate symbols, nudity, violence, and copyrighted assets.

    Targets

    An image target is required. You can provide it to the image moderation workflow by uploading the image in the image field, or provide a URL via the imageURL field.

    Labels

    Our automation system will either APPROVE or REVIEW your images. Your analysts may override the results of Pavlov's automation system via the Pavlov Console.

    Reasons

    Pavlov's automated system will flag images for review for a few reasons. Your decisions in the Pavlov Console can override these decisions, and similar-looking images will inherit these decisions in the future.

    Reason Description
    Hate Symbol If the image may contain a hate symboll.
    Inappropriate Content If the image may contain unsafe content (i.e. nudity, violence, etc.)
    Copyrighted Asset If the image contains a potential copyright violation
    A similar image ... If a similar-looking image's annotation is used.

    Updates

    Updates will be sent to your server's update webhook URL whenever the label on the image changes. You can retrieve the image used to run the request under the data.target.image.rawURL field. Alternatively, verify that the user provided the correct image using the data.target.image.sha256 of the image.

    Workflow: Account Security

    Example: Assess the risk of an actor, given their email and IP address.

    curl "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
      -d email="laika@pavlov.ai" \
      -d ip="127.0.0.1"
    
    // using isomorphic-fetch
    // https://github.com/matthew-andrews/isomorphic-fetch
    
    import 'isomorphic-fetch'
    import fs from 'fs'
    
    const runURL =
      "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    const form = new FormData();
    form.append('email', 'laika@pavlov.ai');
    form.append('ip', '127.0.0.1');
    
    fetch(runURL, { method: 'POST', body: form })
      .then(res => res.json())
      .then(resBody => {
        console.log(resBody.id)
      })
      .catch(err => console.error(err));
    
    # using requests
    # http://docs.python-requests.org/en/master/
    
    import requests
    
    run_url = "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    data = {'email': 'laika@pavlov.ai', 'ip': '127.0.0.1'}
    res = requests.post(run_url, data=data)
    print(res.json()['id'])
    
    # using rest-client
    # https://github.com/rest-client/rest-client
    
    require "json"
    require "rest-client"
    
    run_url = "https://api.pavlov.ai/v1/run/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    res = RestClient.post(run_url, email: 'laika@pavlov.ai', ip: '127.0.0.1')
    id = JSON.parse(res.body)
    puts id
    

    The response will be JSON formatted and contain the target’s unique identifier.

    {
      "id": "TRGXXXXXXXXXXXXXXXXXXXXXX"
    }
    

    Asynchronous updates to targets will be sent to your update webhook URL.

    {
      "data": {
        "target": {
          "id": "TRGXXXXXXXXXXXXXXXXXXXXXX",
          "label": "DENY",
          "score": 1.0,
          "reasons": ["email matched"],
          "updatedAt": "2017-11-02T21:24:56.224Z",
          "actor": {
            "display": "Alex Kern",
            "email": {
              "display": "alex@pavlov.ai"
            }
          }
        }
      }
    }
    

    Monitor your user accounts for potential security concerns. This workflow uses Pavlov Entity Graph to resolve an actor's email to a real person. We assess the risk of the actor based on this information, and warn you of potential account takeovers or botting activity.

    Targets

    An actor target is required. You can provide it to the workflow by providing the user's email in the email field. You may additionally provide the user's IP address via the ip field.

    Labels

    Our automation system will either APPROVE or REVIEW your actors. Your analysts may override the results of Pavlov's automation system via the Pavlov Console.

    Reasons

    Scores and reasons incorporate multiple features about the customer. Features which are given higher weight have a greater effect on the score than features with low weight.

    Reason Weight Description
    IP Blacklist ⭐️⭐️⭐️ If the actor’s IP address is part of a blacklist.
    Email Blacklist ⭐️⭐️⭐️ If the actor’s email address is part of a blacklist.
    Phone Number Blacklist ⭐️⭐️⭐️ If the actor’s phone number is part of a blacklist.
    Email Valid ⭐️⭐️⭐️ If the actor’s email address is of a valid format.
    Email Found ⭐️⭐️⭐️ If the actor’s email address has been seen before.
    Name Match ⭐️⭐️⭐️ If the actor’s name matches the given name.
    Disposable/Free Email ⭐️⭐️ If the actor’s email address is from a disposable account.
    High-risk Location ⭐️⭐️ If the actor’s session comes from a high-risk location.
    New Actor ⭐⭐ If the actor has minimal information related to them.
    Social Profile Found ⭐️ If the actor has an active social profile.

    Updates

    Updates will be sent to your server's update webhook URL whenever the label on the actor changes. You can retrieve the actor used to run the request under the data.target.actor.email.display field.