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 walks you through creating your first loop, adding reviewers, and processing your first request.What You’ll Build
In this tutorial, you’ll create a Content Moderation Loop that:- Receives flagged content from your application
- Automatically invites reviewers with QR codes and invite links
- Routes requests to human reviewers via mobile notifications
- Returns structured human decisions back to your system
By the end of this guide, you’ll have a fully functional loop with invite codes, QR codes, and the ability to process real requests.
Prerequisites
Before you begin, ensure you have:- ✅ A HITL.sh account (sign up at my.hitl.sh)
- ✅ Your API key generated and ready
- ✅ Basic understanding of REST APIs
- ✅ Team members who will act as reviewers (with email addresses)
Generate API Key
If you haven’t created your API key yet, complete this step first.
Step 1: Create the Loop
Using the API
Create your loop using the HITL.sh API. When you create a loop, you automatically become a member and receive invitation codes for sharing:Save the
invite_code
, join_url
, and qr_code_url
from the response - you’ll need these to invite reviewers to your loop.Step 2: Add Reviewers
Your loop needs human reviewers to process requests. Share the invitation information from Step 1 to add team members:Invitation Methods
Share Invite Code
Give reviewers the invite code (e.g.,
ABC123DEF
) to enter in the mobile app.Share Join URL
Send the join URL via email or chat for one-click joining.
Share QR Code
Display or share the QR code image for quick mobile scanning.
Email Invitation
Send invitation emails directly through your dashboard.
Mobile App Setup
Reviewers need the HITL.sh mobile app to receive notifications and respond to requests:1
Download App
Reviewers download the HITL.sh mobile app from their app store.
2
Join Loop
Using one of the invitation methods above (code, URL, or QR scan).
3
Enable Notifications
Ensure push notifications are enabled for instant request alerts.
4
Test Connection
Reviewers should see the loop appear in their app and receive a welcome notification.
Mobile App Guide
Step-by-step guide for reviewers to join loops using the mobile app.
Step 3: Create Your First Request
Now that your loop is set up with reviewers, create your first request to test the workflow:Request Structure
Requests in HITL.sh consist of:Required Fields
Required Fields
- processing_type:
time-sensitive
ordeferred
- type: Content type (
markdown
orimage
) - priority:
low
,medium
,high
, orcritical
- request_text: The main content to review (1-2000 characters)
- response_type: Expected response format
- response_config: Configuration for the response type
- default_response: Fallback response if timeout occurs
- platform: Source platform creating the request
Optional Fields
Optional Fields
- image_url: Required when type is
image
- context: Additional JSON data for context
- timeout_seconds: Custom timeout (60-86400 seconds)
- callback_url: Webhook URL for response notifications
- platform_version: Version of the creating platform
Response Type Options
Configure what decisions reviewers can make:Single Select
Choose one option (Approve, Reject, Escalate)
Multi Select
Select multiple issues or categories
Text
Provide detailed written feedback
Rating
Rate content on a numeric scale
Number
Enter specific numeric values
Boolean
Simple yes/no or true/false decisions
Step 4: Submit Your First Request
Create a test request to verify your loop is working properly. Use the loop ID from Step 1:Your reviewers will immediately receive push notifications on their mobile devices about this new request!
Step 5: Monitor Request Progress
Track your request and wait for reviewer responses:Check Request Status
Use the polling URL from the response to check status:Request Lifecycle
1
Created & Broadcasted
Request is created and push notifications sent to all active reviewers.
2
Pending Review
Waiting for a reviewer to claim and respond to the request.
3
Claimed
A reviewer has opened the request and is working on it.
4
Completed
Reviewer has submitted their response - human decision is ready!
5
Webhook Notification
If configured, your callback URL receives the response data.
Receiving Human Decisions
Using Webhooks (Recommended)
Set up webhooks for real-time notifications when requests complete:Using Polling
If webhooks aren’t available, poll the request status periodically:Best Practices
Clear Request Context
Provide sufficient context in
request_text
and context
fields for informed decisions.Appropriate Timeouts
Set realistic
timeout_seconds
based on request complexity and reviewer availability.Meaningful Default Responses
Choose safe default responses that represent the best fallback decision.
Response Type Selection
Match response types to your use case - single select for decisions, text for feedback.
Request Optimization
Priority Levels
Priority Levels
- Critical: Security issues, policy violations (< 15 min response)
- High: Time-sensitive content decisions (< 1 hour)
- Medium: Standard content review (< 4 hours)
- Low: Quality improvements, feedback (< 24 hours)
Context Information
Context Information
Include relevant context to help reviewers make informed decisions:
- User information and history
- Automated system flags and confidence scores
- Related content or previous decisions
- Business context and implications
Response Configuration
Response Configuration
Design response options that are:
- Mutually exclusive for single select
- Comprehensive covering all possible decisions
- Clear and actionable with no ambiguity
- Consistent with your business logic
Troubleshooting
No Notifications Sent
No Notifications Sent
Symptoms:
notifications_sent: 0
in responseSolutions:- Verify reviewers have joined the loop successfully
- Check if reviewers have push notifications enabled
- Ensure reviewers are active (not in do-not-disturb mode)
- Confirm the mobile app is installed and logged in
Request Not Appearing for Reviewers
Request Not Appearing for Reviewers
Symptoms: Request created but reviewers don’t see itSolutions:
- Check if
broadcasted_to
count matches expected reviewers - Verify reviewers are members of the correct loop
- Ensure loop ID in the request URL is correct
- Check if reviewers are filtering requests by priority
Polling Not Working
Polling Not Working
Symptoms: Request status always shows “pending”Solutions:
- Verify the request ID is correct
- Check API key permissions for request access
- Ensure you’re polling the correct endpoint
- Wait for reviewers to actually respond to the request
Webhook Not Triggered
Webhook Not Triggered
Symptoms: No webhook calls when request completesSolutions:
- Verify
callback_url
is publicly accessible - Check webhook endpoint returns 200 status
- Ensure webhook URL uses HTTPS
- Test with webhook debugging tools like ngrok
Next Steps
🎉 Congratulations! You’ve successfully created your first loop and processed a request. Here’s what to explore next:Response Types Guide
Learn about all available response types and their configurations.
Mobile App Guide
Help your reviewers master the mobile app interface.
Webhook Setup
Configure webhooks for real-time response notifications.
API Reference
Explore all available API endpoints and advanced features.
Production Checklist
Before deploying to production:- ✅ Test with multiple reviewers to ensure proper load distribution
- ✅ Configure webhooks for automated response processing
- ✅ Set up monitoring for request volume and response times
- ✅ Train reviewers on your specific guidelines and criteria
- ✅ Test timeout scenarios to validate default response handling
- ✅ Implement retry logic for API calls and webhook handling