Requests

Requests are the core data units that flow through HITL.sh loops. Each request represents a piece of content, decision, or action that requires human review and approval before proceeding.

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
Suspicious financial transactions
AI-generated content for quality review
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 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 Types

Text-Based Requests

Review written content for appropriateness, accuracy, or compliance:

text_request = {
    "content": "User submitted comment text",
    "content_type": "text",
    "ai_analysis": {
        "confidence": 0.65,
        "flags": ["potential_hate_speech"],
        "risk_score": 0.7
    },
    "context": {
        "language": "en",
        "content_length": 150,
        "contains_links": False
    }
}

Image-Based Requests

Review visual content for inappropriate material or quality issues:

image_request = {
    "content": "base64_encoded_image_data",
    "content_type": "image",
    "ai_analysis": {
        "confidence": 0.45,
        "flags": ["potential_nudity", "violence"],
        "risk_score": 0.9
    },
    "context": {
        "image_format": "jpeg",
        "dimensions": "1920x1080",
        "file_size": 245760,
        "upload_source": "mobile_app"
    }
}

Video-Based Requests

Review video content for compliance or quality standards:

video_request = {
    "content": "video_file_url",
    "content_type": "video",
    "ai_analysis": {
        "confidence": 0.35,
        "flags": ["potential_copyright_violation"],
        "risk_score": 0.6
    },
    "context": {
        "duration": 180,
        "format": "mp4",
        "resolution": "1080p",
        "audio_track": True
    }
}

Document-Based Requests

Review documents for accuracy, completeness, or compliance:

document_request = {
    "content": "document_file_url",
    "content_type": "document",
    "ai_analysis": {
        "confidence": 0.55,
        "flags": ["missing_required_fields"],
        "risk_score": 0.4
    },
    "context": {
        "document_type": "expense_report",
        "file_format": "pdf",
        "page_count": 3,
        "submission_date": "2024-01-15"
    }
}

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.

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

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.

Quality Assurance

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?

Explore Request Types

Learn about different types of requests you can create.

Create Your First Loop

Set up a loop to process your requests.

API Reference

Detailed API documentation for request management.

Getting Started

Core Concepts

Mobile App

Requests

Responses

Integrations

Webhooks

​Requests

​What are Requests?

Request Examples

​Request Lifecycle

​1. Creation

​2. Routing

​3. Review

​4. Completion

​Request Structure

​Required Fields

​Optional Fields

​Request Types

​Text-Based Requests

​Image-Based Requests

​Video-Based Requests

​Document-Based Requests

​Request Priority Levels

​Low Priority

​Normal Priority

​High Priority

​Urgent Priority

​Request States

Pending

Assigned

In Review

Completed

Escalated

Timed Out

​Best Practices

​Request Design

​Performance Optimization

Batch Processing

Smart Routing

Load Balancing

Priority Queuing

​Quality Assurance

​API Integration

​Creating Requests

​Retrieving Responses

​Next Steps

Explore Request Types

Create Your First Loop

API Reference

Requests

What are Requests?

Request Lifecycle

1. Creation

2. Routing

3. Review

4. Completion

Request Structure

Required Fields

Optional Fields

Request Types

Text-Based Requests

Image-Based Requests

Video-Based Requests

Document-Based Requests

Request Priority Levels

Low Priority

Normal Priority

High Priority

Urgent Priority

Request States

Best Practices

Request Design

Performance Optimization

Quality Assurance

API Integration

Creating Requests

Retrieving Responses

Next Steps