Quickstart Guide

Build your first HITL (Human-in-the-Loop) workflow in under 10 minutes. This tutorial walks you through creating a content moderation workflow where human reviewers evaluate user-generated content.

What You’ll Build: A content moderation workflow that receives flagged content via webhook, routes it to human reviewers, and returns their decision.

Prerequisites

HITL.sh Account

Development Environment

Python 3.7+, Node.js 16+, or your preferred language with HTTP client support.

Step 1: Get Your API Key

Create your free account at hitl.sh/signup

Generate API Key

Go to your dashboard and create a new API key. Copy and save it securely.

Test Connection

Verify your API key works using the dedicated test endpoint:

curl -X GET https://api.hitl.sh/v1/test \
  -H "Authorization: Bearer your_api_key_here"

You should get a JSON response confirming your API key is valid.

Step 2: Create a Workflow

A workflow is a visual pipeline that routes data through processing steps, including human review. Create one in the dashboard:

Open the Dashboard

Navigate to my.hitl.sh and sign in.

Create a New Workflow

Click Workflows in the sidebar, then click New Workflow. Name it “Content Moderation”.

Add a Human Review Node

In the workflow designer canvas, click the + button on the Trigger node and add a Human Review node. Configure it:

Response type: Single Select
Options: Approve, Reject, Escalate
Reviewers: Select your Universe (all reviewers) or a specific group
Timeout: 3600 seconds (1 hour)
Default response: Reject

Activate the Workflow

Click Save, then toggle Activate. Copy the webhook URL displayed at the top of the designer.

Step 3: Add Reviewers

Your workflow needs human reviewers to respond. Add people in the Humans section of the dashboard:

Navigate to Humans

Click Humans in the sidebar.

Add People

Click Add Person and invite reviewers by email. They will receive an invitation to join HITL.sh.

Download the Mobile App

Reviewers download the HITL.sh mobile app (App Store | Google Play) and sign in to receive push notifications.

For Testing: You can test by adding yourself as a reviewer and responding via the web dashboard inbox or the mobile app.

Step 4: Trigger the Workflow

Send a POST request to your workflow’s webhook URL to start an execution:

Python
Node.js
cURL

import requests

webhook_url = "https://api.hitl.sh/v1/workflows/YOUR_WORKFLOW_ID/trigger"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "content": "Please review this user comment: 'Great product, highly recommend! Check my link for a discount.'",
    "user_id": "user_123",
    "category": "comment"
}

response = requests.post(webhook_url, headers=headers, json=payload)
execution = response.json()

print(f"Execution started: {execution['data']['execution_id']}")

const axios = require('axios');

const webhookUrl = 'https://api.hitl.sh/v1/workflows/YOUR_WORKFLOW_ID/trigger';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};
const payload = {
  content: "Please review this user comment: 'Great product, highly recommend! Check my link for a discount.'",
  user_id: 'user_123',
  category: 'comment'
};

const response = await axios.post(webhookUrl, payload, { headers });
console.log('Execution started:', response.data.data.execution_id);

curl -X POST https://api.hitl.sh/v1/workflows/YOUR_WORKFLOW_ID/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Please review this user comment: Great product, highly recommend!",
    "user_id": "user_123",
    "category": "comment"
  }'

Step 5: Respond and View Results

Reviewers receive a push notification on the mobile app
Open the review request, read the content, and select a response (Approve, Reject, or Escalate)
The workflow execution completes

View the result in the Executions tab of the workflow designer, or poll the execution status via API:

execution_id = "exec_abc123"
status_url = f"https://api.hitl.sh/v1/executions/{execution_id}"
response = requests.get(status_url, headers=headers)
result = response.json()

print(f"Status: {result['data']['status']}")
print(f"Response: {result['data']['response_data']}")

What’s Next?

Workflow Designer

Learn about all node types, canvas controls, and advanced configuration.

Response Types

Explore all seven response types and their configurations.

Mobile App Guide

Learn how reviewers use the mobile app to respond.

Integrations

Connect your workflows to n8n, Zapier, Make, and more.

SDKs

Use our official SDKs for easier integration.

Humans

Set up reviewer groups for targeted assignment.

Getting Started

Integration Guides

Enterprise

Workflow Design

Core Concepts

Mobile App

Features

Responses

Responses

Templates

Examples

Webhooks

Troubleshooting

Integrations

Prerequisites

HITL.sh Account

Development Environment

Step 1: Get Your API Key

Step 2: Create a Workflow

Step 3: Add Reviewers

Step 4: Trigger the Workflow

Step 5: Respond and View Results

What’s Next?

Workflow Designer

Response Types

Mobile App Guide

Integrations

SDKs

Humans

​Prerequisites

HITL.sh Account

Development Environment

​Step 1: Get Your API Key

​Step 2: Create a Workflow

​Step 3: Add Reviewers

​Step 4: Trigger the Workflow

​Step 5: Respond and View Results

​What’s Next?

Workflow Designer

Response Types

Mobile App Guide

Integrations

SDKs

Humans

Prerequisites

Step 1: Get Your API Key

Step 2: Create a Workflow

Step 3: Add Reviewers

Step 4: Trigger the Workflow

Step 5: Respond and View Results

What’s Next?