Requests Introduction

Requests are the fundamental building blocks of HITL.sh workflows. They represent pieces of content, decisions, or actions that require human oversight before proceeding. Understanding how to create and structure requests is essential for building effective human-in-the-loop systems.

What are Requests?

A request in HITL.sh is a structured data package that contains:

Content to Review: The actual material requiring human oversight
Context Information: Background data to help reviewers make decisions
AI Analysis: Results from your AI system’s initial processing
Metadata: Request details like priority, source, and timestamps
Routing Instructions: How the request should be handled

Request Examples

Flagged social media posts for content moderation
Suspicious financial transactions for fraud review
AI-generated content for quality assurance
Customer support tickets requiring escalation
Compliance documents for verification

Request Lifecycle

1. Creation

Requests are created when your AI system or application identifies a need for human review:

def create_review_request(content, ai_analysis):
    request = hitl_client.create_request(
        loop_id="content_moderation",
        data={
            "content": content.text,
            "content_type": "text",
            "priority": determine_priority(ai_analysis.risk_score),
            "ai_analysis": {
                "confidence": ai_analysis.confidence,
                "flags": ai_analysis.flags,
                "risk_score": ai_analysis.risk_score,
                "model_version": ai_analysis.model_version
            },
            "metadata": {
                "user_id": content.user_id,
                "timestamp": content.created_at,
                "source": "social_media_api",
                "previous_flags": get_user_flag_count(content.user_id)
            }
        }
    )
    return request

2. Routing

Requests are automatically routed to appropriate reviewers based on:

Reviewer Skills

Workload Balance

Priority Rules

Escalation Paths

3. Review

Human reviewers examine the request and provide their decision:

Diagram showing the request review process flow

4. Completion

The human decision is processed and returned to your system:

def handle_completed_request(request_id):
    response = hitl_client.get_response(request_id)
    
    # Process the human decision
    if response.decision == "approved":
        process_approval(response)
    elif response.decision == "rejected":
        process_rejection(response)
    elif response.decision == "needs_changes":
        request_modifications(response)
    elif response.decision == "escalate":
        escalate_to_senior_reviewer(response)
    
    # Update your system's state
    update_request_status(request_id, response.decision)
    
    # Log the decision for analytics
    log_decision(request_id, response)

Request Types

HITL.sh supports multiple content types, each with specific handling requirements:

Text-Based Requests

Review written content for appropriateness, accuracy, or compliance.

Image-Based Requests

Review visual content for inappropriate material or quality issues.

Video-Based Requests

Review video content for compliance or quality standards.

Document-Based Requests

Review documents for accuracy, completeness, or compliance.

Request Structure

Required Fields

Every request must include these essential elements:

{
  "loop_id": "string",
  "content": "string",
  "content_type": "text|image|video|document",
  "priority": "low|normal|high|urgent"
}

Optional Fields

Enhance requests with additional context:

{
  "ai_analysis": {
    "confidence": 0.75,
    "flags": ["potential_harm", "inappropriate_language"],
    "risk_score": 0.8,
    "model_version": "v2.1.0",
    "processing_time": 0.15
  },
  "metadata": {
    "user_id": "user_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "source": "api_endpoint",
    "session_id": "sess_abc",
    "ip_address": "192.168.1.1"
  },
  "context": {
    "previous_decisions": 3,
    "user_reputation": "trusted",
    "content_category": "user_generated",
    "language": "en"
  }
}

Request Priority Levels

Low Priority

Standard requests with no time sensitivity:

Response Time: 24-48 hours
Reviewer Level: Junior reviewers
Examples: General content moderation, routine quality checks

Normal Priority

Standard business requests:

Response Time: 4-8 hours
Reviewer Level: Standard reviewers
Examples: Content approval, expense reports under threshold

High Priority

Time-sensitive requests requiring prompt attention:

Response Time: 1-2 hours
Reviewer Level: Senior reviewers or multiple reviewers
Examples: Customer escalations, urgent compliance reviews

Urgent Priority

Critical requests requiring immediate attention:

Response Time: 15-30 minutes
Reviewer Level: Senior reviewers, managers, or escalation team
Examples: Security incidents, legal compliance issues, customer complaints

Request States

Track the progress of requests through their lifecycle:

Pending

Request is waiting to be assigned to a reviewer.

Assigned

Request has been assigned to a specific reviewer.

In Review

Reviewer is actively examining the request.

Completed

Human decision has been made and returned.

Escalated

Request has been escalated to a senior reviewer.

Timed Out

Request exceeded response time and was auto-processed.

Creating Effective Requests

Content Presentation

Clear Formatting

Present content in a format that’s easy for reviewers to understand.

Relevant Context

Include all information reviewers need to make informed decisions.

Structured Data

Organize request data logically with consistent formatting.

Appropriate Priority

Set realistic priorities based on business impact and urgency.

AI Analysis Integration

Confidence Scores

Include AI confidence levels to help reviewers understand uncertainty.

Flagged Issues

Highlight specific concerns the AI has identified.

Risk Assessment

Provide risk scores and reasoning for human consideration.

Model Information

Include AI model version and processing details for transparency.

Request Performance

Metrics to Track

Monitor request performance to optimize your workflows:

Response Time Metrics

Quality Metrics

Volume Metrics

Optimization Strategies

Batch Processing

Group similar requests to reduce reviewer overhead.

Smart Routing

Route requests to reviewers with appropriate expertise.

Load Balancing

Distribute requests evenly across your reviewer team.

Priority Queuing

Process high-priority requests before lower-priority ones.

Best Practices

Request Design

Clear Content

Present content in a format that’s easy for reviewers to understand.

Relevant Context

Include all information reviewers need to make informed decisions.

Structured Data

Organize request data logically with consistent formatting.

Appropriate Priority

Set realistic priorities based on business impact and urgency.

Performance Optimization

Validation: Verify request data before submission
Consistency: Maintain consistent request structure across loops
Monitoring: Track request processing times and success rates
Feedback: Use reviewer feedback to improve request quality

API Integration

Creating Requests

import requests

def submit_request(loop_id, request_data):
    response = requests.post(
        f"https://api.hitl.sh/v1/loops/{loop_id}/requests",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json=request_data
    )
    
    if response.status_code == 201:
        return response.json()
    else:
        raise Exception(f"Failed to create request: {response.text}")

Retrieving Responses

def get_request_response(request_id):
    response = requests.get(
        f"https://api.hitl.sh/v1/requests/{request_id}/response",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        return None  # Response not ready yet

Next Steps

Ready to start creating requests for your loops?

Text-Based Requests

Learn how to create and structure text-based review requests.

Image-Based Requests

Understand how to handle image content for human review.

Video-Based Requests

Explore video content review workflows and best practices.

Create Your First Loop

Set up a loop to process your requests.

Getting Started

Core Concepts

Mobile App

Requests

Responses

Integrations

Webhooks

​Requests Introduction

​What are Requests?

Request Examples

​Request Lifecycle

​1. Creation

​2. Routing

​3. Review

​4. Completion

​Request Types

Text-Based Requests

Image-Based Requests

Video-Based Requests

Document-Based Requests

​Request Structure

​Required Fields

​Optional Fields

​Request Priority Levels

​Low Priority

​Normal Priority

​High Priority

​Urgent Priority

​Request States

Pending

Assigned

In Review

Completed

Escalated

Timed Out

​Creating Effective Requests

​Content Presentation

​AI Analysis Integration

Confidence Scores

Flagged Issues

Risk Assessment

Model Information

​Request Performance

​Metrics to Track

​Optimization Strategies

​Best Practices

​Request Design

Clear Content

Relevant Context

Structured Data

Appropriate Priority

​Performance Optimization

​API Integration

​Creating Requests

​Retrieving Responses

​Next Steps

Text-Based Requests

Image-Based Requests

Video-Based Requests

Create Your First Loop

Requests Introduction

What are Requests?

Request Lifecycle

1. Creation

2. Routing

3. Review

4. Completion

Request Types

Request Structure

Required Fields

Optional Fields

Request Priority Levels

Low Priority

Normal Priority

High Priority

Urgent Priority

Request States

Creating Effective Requests

Content Presentation

AI Analysis Integration

Request Performance

Metrics to Track

Optimization Strategies

Best Practices

Request Design

Performance Optimization

API Integration

Creating Requests

Retrieving Responses

Next Steps