> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitl.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests Introduction

> Learn about the different types of requests in HITL.sh and how they enable human-in-the-loop workflows

# 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

<Card title="Request Examples" icon="file-text">
  - 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
</Card>

## Request Lifecycle

Requests follow a straightforward lifecycle from creation to completion:

### 1. Creation

Your application creates a request using the API, specifying the content type, response requirements, and reviewer instructions:

```python theme={null}
import requests

# Create the request
request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown", 
    "priority": "high",
    "request_text": "Review this comment: 'Great product! Use my referral code SAVE20.'",
    "response_type": "single_select",
    "response_config": {
        "options": [
            {"value": "approve", "label": "✅ Approve", "color": "#22c55e"},
            {"value": "reject", "label": "❌ Reject", "color": "#ef4444"}
        ],
        "required": True
    },
    "default_response": "reject",
    "timeout_seconds": 3600,
    "platform": "api"
}

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{loop_id}/requests",
    headers={"Authorization": f"Bearer {api_key}"},
    json=request_data
)

request_id = response.json()["data"]["request_id"]
```

### 2. Broadcasting

The API immediately sends push notifications to all active members of the target loop. Members receive the request in their mobile app with priority-based ordering.

### 3. Pending

The request waits in the queue for a reviewer to respond. Requests are ordered by priority (critical → high → medium → low) and creation time.

### 4. Completed

The reviewer submits their response using the configured response type. The request status changes to "completed" and the response data becomes available via the API.

### 5. Webhook (Optional)

If you configured a `callback_url`, HITL.sh sends a webhook notification with the response data to your endpoint.

### Retrieving the Response

```python theme={null}
# Poll for the completed response
def get_response(request_id):
    response = requests.get(
        f"https://api.hitl.sh/v1/api/requests/{request_id}",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    
    if response.status_code == 200:
        data = response.json()["data"]["request"]
        
        if data["status"] == "completed":
            # Process the human response
            response_data = data["response_data"]
            
            if data["response_type"] == "single_select":
                decision = response_data["selected_value"]
                if decision == "approve":
                    approve_content()
                elif decision == "reject":
                    reject_content()
                    
        elif data["status"] == "timeout":
            # Handle timeout using default response
            default_response = data["default_response"]
            handle_timeout_response(default_response)
            
        return data
    
    return None
```

## Request Content Types

HITL.sh supports two content types for human review:

<CardGroup cols={2}>
  <Card title="Markdown Requests" icon="file-text">
    Review text-based content like comments, posts, articles, or documents formatted in markdown
  </Card>

  <Card title="Image Requests" icon="image">
    Review visual content like photos, graphics, or screenshots requiring human evaluation
  </Card>
</CardGroup>

### Markdown Content Type

Use `type: "markdown"` for text-based content review:

```python theme={null}
request_data = {
    "type": "markdown",
    "request_text": "Please review this user comment: 'Great product! I've been using it for 6 months and highly recommend it.'",
    "response_type": "single_select",
    "response_config": {
        "options": [
            {"value": "approve", "label": "✅ Approve", "color": "#22c55e"},
            {"value": "reject", "label": "❌ Reject", "color": "#ef4444"}
        ]
    }
}
```

### Image Content Type

Use `type: "image"` for visual content review:

```python theme={null}
request_data = {
    "type": "image",
    "request_text": "Review this uploaded profile photo for appropriateness",
    "image_url": "https://example.com/uploads/profile_123.jpg",
    "response_type": "single_select",
    "response_config": {
        "options": [
            {"value": "approve", "label": "✅ Appropriate"},
            {"value": "reject", "label": "❌ Inappropriate"}
        ]
    },
    "default_response": "reject"
}
```

## Request Structure

### Required Fields

Every request must include these essential elements:

```json theme={null}
{
  "processing_type": "time-sensitive|deferred",
  "type": "markdown|image",
  "priority": "low|medium|high|critical",
  "request_text": "string",
  "response_type": "text|single_select|multi_select|rating|number",
  "response_config": "object",
  "default_response": "varies by response_type",
  "platform": "api"
}
```

### Optional Fields

Enhance requests with additional context and configuration:

```json theme={null}
{
  "image_url": "https://example.com/image.jpg",
  "context": {
    "user_id": "user_123", 
    "post_id": "post_456",
    "automated_flags": ["potential_spam"],
    "previous_violations": 2
  },
  "timeout_seconds": 3600,
  "callback_url": "https://example.com/webhook/response",
  "platform": "api",
  "platform_version": "1.0.0"
}
```

## Request Priority Levels

### Low Priority

Standard requests with no time sensitivity:

* **Response Time**: 24-48 hours
* **Reviewer Level**: Any available reviewer
* **Examples**: General content moderation, routine quality checks

### Medium Priority

Standard business requests:

* **Response Time**: 4-8 hours
* **Reviewer Level**: Standard reviewers
* **Examples**: Content approval, user reports, policy reviews

### High Priority

Time-sensitive requests requiring prompt attention:

* **Response Time**: 1-2 hours
* **Reviewer Level**: Experienced reviewers
* **Examples**: Customer escalations, urgent compliance reviews

### Critical Priority

Critical requests requiring immediate attention:

* **Response Time**: 15-30 minutes
* **Reviewer Level**: Senior reviewers or escalation team
* **Examples**: Security incidents, legal compliance issues, emergency reviews

## Request States

Track the progress of requests through their lifecycle:

<CardGroup cols={2}>
  <Card title="Pending" icon="clock">
    Request is waiting for a reviewer to respond.
  </Card>

  <Card title="Completed" icon="check">
    Human decision has been made and returned.
  </Card>

  <Card title="Timeout" icon="alert">
    Request exceeded response time and default response was used.
  </Card>

  <Card title="Cancelled" icon="x">
    Request was cancelled before completion by the creator.
  </Card>
</CardGroup>

## Creating Effective Requests

### Content Presentation

<Steps>
  <Step title="Clear Formatting">
    Present content in a format that's easy for reviewers to understand.
  </Step>

  <Step title="Relevant Context">
    Include all information reviewers need to make informed decisions.
  </Step>

  <Step title="Structured Data">
    Organize request data logically with consistent formatting.
  </Step>

  <Step title="Appropriate Priority">
    Set realistic priorities based on business impact and urgency.
  </Step>
</Steps>

### AI Analysis Integration

<CardGroup cols={2}>
  <Card title="Confidence Scores" icon="target">
    Include AI confidence levels to help reviewers understand uncertainty.
  </Card>

  <Card title="Flagged Issues" icon="flag">
    Highlight specific concerns the AI has identified.
  </Card>

  <Card title="Risk Assessment" icon="alert-triangle">
    Provide risk scores and reasoning for human consideration.
  </Card>

  <Card title="Model Information" icon="info">
    Include AI model version and processing details for transparency.
  </Card>
</CardGroup>

## Request Performance

### Metrics to Track

Monitor request performance to optimize your workflows:

<AccordionGroup>
  <Accordion title="Response Time Metrics">
    * Average response time per request type
    * 95th percentile response times
    * Time to first response
    * Escalation frequency and timing
  </Accordion>

  <Accordion title="Quality Metrics">
    * Decision consistency across reviewers
    * Inter-rater reliability scores
    * Error rates and types
    * Reviewer performance trends
  </Accordion>

  <Accordion title="Volume Metrics">
    * Requests per day/week/month
    * Peak load times and patterns
    * Queue length and processing capacity
    * Loop utilization rates
  </Accordion>
</AccordionGroup>

### Optimization Strategies

<Steps>
  <Step title="Batch Processing">
    Group similar requests to reduce reviewer overhead.
  </Step>

  <Step title="Smart Routing">
    Route requests to reviewers with appropriate expertise.
  </Step>

  <Step title="Load Balancing">
    Distribute requests evenly across your reviewer team.
  </Step>

  <Step title="Priority Queuing">
    Process high-priority requests before lower-priority ones.
  </Step>
</Steps>

## Best Practices

### Request Design

<CardGroup cols={2}>
  <Card title="Clear Content" icon="eye">
    Present content in a format that's easy for reviewers to understand.
  </Card>

  <Card title="Relevant Context" icon="info">
    Include all information reviewers need to make informed decisions.
  </Card>

  <Card title="Structured Data" icon="database">
    Organize request data logically with consistent formatting.
  </Card>

  <Card title="Appropriate Priority" icon="flag">
    Set realistic priorities based on business impact and urgency.
  </Card>
</CardGroup>

### 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

## Complete Examples

### Content Moderation (Markdown)

Review text content for community guidelines:

```python theme={null}
import requests

# Create a markdown content review request
request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown", 
    "priority": "high",
    "request_text": "Review this user comment for community guidelines: 'This product is amazing! Everyone should try it. Use code SAVE20 for discount.'",
    "context": {
        "user_id": "user_12345",
        "comment_id": "comment_789",
        "automated_flags": ["promotional_content"]
    },
    "timeout_seconds": 1800,
    "response_type": "single_select",
    "response_config": {
        "options": [
            {"value": "approve", "label": "✅ Approve", "color": "#22c55e"},
            {"value": "reject", "label": "❌ Reject", "color": "#ef4444"},
            {"value": "edit", "label": "✏️ Needs Editing", "color": "#f59e0b"}
        ],
        "required": True
    },
    "default_response": "reject",
    "platform": "api"
}

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{loop_id}/requests",
    headers={"Authorization": f"Bearer {api_key}"},
    json=request_data
)
```

### Image Moderation

Review visual content for appropriateness:

```python theme={null}
# Create an image review request
request_data = {
    "processing_type": "time-sensitive",
    "type": "image",
    "priority": "high",
    "request_text": "Review this uploaded profile photo for appropriateness and compliance with our image guidelines.",
    "image_url": "https://cdn.example.com/uploads/profile_photos/user_12345.jpg",
    "context": {
        "user_id": "user_12345",
        "upload_timestamp": "2024-01-15T10:30:00Z",
        "file_size": "2.4MB"
    },
    "timeout_seconds": 900,
    "response_type": "single_select",
    "response_config": {
        "options": [
            {"value": "approve", "label": "✅ Approve Image", "color": "#22c55e"},
            {"value": "reject", "label": "❌ Reject Image", "color": "#ef4444"},
            {"value": "flag", "label": "🚩 Flag for Review", "color": "#f59e0b"}
        ],
        "required": True
    },
    "default_response": "reject",  # Conservative default
    "platform": "api"
}

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{loop_id}/requests",
    headers={"Authorization": f"Bearer {api_key}"},
    json=request_data
)
```

### Retrieving Responses

```python theme={null}
def get_request_status(request_id):
    response = requests.get(
        f"https://api.hitl.sh/v1/api/requests/{request_id}",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    
    if response.status_code == 200:
        data = response.json()["data"]["request"]
        
        if data["status"] == "completed":
            return {
                "completed": True,
                "response_data": data["response_data"],
                "response_by": data["response_by_user"]["name"],
                "completion_time": data["completed_at"]
            }
        else:
            return {
                "completed": False,
                "status": data["status"],
                "timeout_at": data.get("timeout_at")
            }
    
    return None
```

## Next Steps

Ready to start creating requests for your loops?

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/requests/create-request">
    See the complete API documentation for creating requests with all parameters and examples.
  </Card>

  <Card title="Response Types" icon="message-circle" href="/responses/types">
    Learn about the 5 response types you can use to collect structured feedback from reviewers.
  </Card>

  <Card title="Create Your First Loop" icon="users" href="/first-loop">
    Set up a loop with reviewers to process your requests.
  </Card>

  <Card title="Mobile App Guide" icon="mobile" href="/mobile/responding">
    Understand how reviewers interact with your requests on the mobile app.
  </Card>
</CardGroup>