curl -X POST 'https://api.hitl.sh/v1/loops' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Content Moderation",
    "description": "Review flagged content for inappropriate material",
    "settings": {
      "required_approvals": 1,
      "auto_approve_after": 14400,
      "priority": "normal"
    }
  }'

{
  "id": "loop_abc123",
  "name": "Content Moderation",
  "description": "Review flagged content for inappropriate material",
  "status": "active",
  "settings": {
    "required_approvals": 1,
    "auto_approve_after": 14400,
    "priority": "normal"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

​
Creating Your First Loop

A loop in HITL.sh is a human-in-the-loop workflow that routes requests to human reviewers when AI systems need human oversight. This guide will walk you through creating your first loop from start to finish.

​
What You’ll Build

In this tutorial, you’ll create a Content Moderation Loop that:
  • Receives flagged content from your AI system
  • Routes it to human reviewers for approval
  • Returns the human decision to complete the workflow
By the end of this guide, you’ll have a fully functional loop that can process real requests.

​
Prerequisites

Before you begin, ensure you have:
  • ✅ A HITL.sh account with API access
  • ✅ Your API key generated and ready
  • ✅ At least one reviewer added to your team
  • ✅ Basic understanding of REST APIs

Set Up API Keys

If you haven’t generated your API key yet, complete this step first.

​
Step 1: Create the Loop

​
Using the Dashboard

1

Navigate to Loops

From your dashboard, click “Loops” in the sidebar, then click “Create New Loop”.
2

Configure Basic Settings

Fill in the loop details:
  • Name: Content Moderation
  • Description: Review flagged content for inappropriate material
  • Priority: Normal
  • Response Time: 2 hours
3

Set Review Requirements

Configure how many reviewers need to approve each request:
  • Required Approvals: 1
  • Auto-approve after: 4 hours (if no response)

​
Using the API

Alternatively, create the loop programmatically: 
curl -X POST 'https://api.hitl.sh/v1/loops' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Content Moderation",
    "description": "Review flagged content for inappropriate material",
    "settings": {
      "required_approvals": 1,
      "auto_approve_after": 14400,
      "priority": "normal"
    }
  }'

{
  "id": "loop_abc123",
  "name": "Content Moderation",
  "description": "Review flagged content for inappropriate material",
  "status": "active",
  "settings": {
    "required_approvals": 1,
    "auto_approve_after": 14400,
    "priority": "normal"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

​
Step 2: Add Reviewers

Your loop needs human reviewers to process requests. Add team members who will review content:
1

Invite Reviewers

From the loop settings, click “Add Reviewers” and enter email addresses.
2

Set Skills

Assign content moderation expertise to reviewers:
  • Primary Skills: Content Moderation, Safety
  • Secondary Skills: Language, Cultural Context
3

Configure Availability

Set when reviewers are available to respond to requests.
Reviewers will receive email invitations and can join using the mobile app or web interface.

​
Step 3: Configure Request Fields

Define what information reviewers need to make decisions:

​
Step 4: Set Response Options

Configure what decisions reviewers can make:

Approved

Content passes moderation and can be published.

Rejected

Content violates guidelines and should be removed.

Needs Changes

Content requires modifications before approval.

Escalate

Send to senior moderator for review.

​
Step 5: Test Your Loop

Before going live, test your loop with sample requests: 
curl -X POST 'https://api.hitl.sh/v1/loops/loop_abc123/requests' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "This is a test message for content moderation",
    "flag_reason": "Potential inappropriate language",
    "confidence_score": 0.75,
    "category": "text"
  }'

{
  "id": "req_xyz789",
  "loop_id": "loop_abc123",
  "status": "pending",
  "content": "This is a test message for content moderation",
  "created_at": "2024-01-15T10:35:00Z"
}

​
Step 6: Monitor and Respond

Once your loop is active:
1

Reviewer Notification

Reviewers receive push notifications and emails about new requests.
2

Mobile Review

Reviewers can respond using the HITL.sh mobile app.
3

Decision Processing

Human decisions are automatically sent back to your system via webhooks.

​
Integration with Your System

​
Webhook Configuration

Set up webhooks to receive human decisions: 
curl -X POST 'https://api.hitl.sh/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-app.com/webhooks/hitl",
    "events": ["request.completed"],
    "loop_id": "loop_abc123"
  }'

​
Processing Responses

Handle webhook payloads in your application: 
from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhooks/hitl', methods=['POST'])
def handle_hitl_webhook():
    payload = request.json
    
    if payload['event'] == 'request.completed':
        request_id = payload['data']['request_id']
        decision = payload['data']['decision']
        
        # Process the human decision
        if decision == 'approved':
            publish_content(request_id)
        elif decision == 'rejected':
            remove_content(request_id)
        elif decision == 'needs_changes':
            request_changes(request_id)
    
    return {'status': 'success'}, 200

​
Best Practices

Clear Guidelines

Provide reviewers with clear criteria for making decisions.

Regular Training

Keep reviewers updated on policy changes and edge cases.

Performance Monitoring

Track response times and decision consistency.

Feedback Loop

Use reviewer feedback to improve AI flagging accuracy.

​
Troubleshooting

​
Next Steps

Congratulations! You’ve created your first loop. Now explore:

Advanced Loop Features

Configure escalations, routing rules, and advanced settings.

Mobile App Setup

Get your team set up with the mobile app for on-the-go reviews.

Analytics Dashboard

Monitor loop performance and optimize your workflows.

Additional Integrations

Connect HITL.sh with your existing tools and platforms.