Add Request Feedback - Human in the Loop

POST

api

requests

{id}

feedback

curl -X POST https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348/feedback \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }'

{
  "error": false,
  "msg": "Feedback added successfully",
  "data": {
    "request_id": "65f1234567890abcdef12348",
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }
}

Add feedback to completed requests to help improve reviewer performance and overall system quality. Feedback can include ratings, comments, and specific quality metrics that help reviewers understand what worked well and what could be improved.

Authentication

Authorization

string

required

Your API key for authentication

Path Parameters

string

required

The unique identifier of the completed request

Body Parameters

feedback

object

required

Feedback object containing ratings, comments, and quality metrics

Feedback Object Structure

The feedback object can contain any combination of the following fields:

feedback.rating

number

Overall quality rating (1-5 scale, where 5 is excellent)

feedback.comment

string

Free-form text feedback and comments (max 1000 characters)

feedback.accuracy

number

Response accuracy rating (1-5 scale)

feedback.timeliness

number

Response timeliness rating (1-5 scale)

feedback.helpfulness

number

Response helpfulness rating (1-5 scale)

Whether you would recommend this reviewer for similar requests

feedback.tags

array

Array of feedback tags (e.g., [“thorough”, “quick”, “insightful”])

feedback.follow_up_needed

boolean

Whether this request requires follow-up action

feedback.category

string

Feedback category: “positive”, “constructive”, “issue”

Response

error

boolean

Whether an error occurred

msg

string

Success message

data

object

Show data

request_id

string

ID of the request that received feedback

feedback

object

The feedback object that was submitted

curl -X POST https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348/feedback \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }'

{
  "error": false,
  "msg": "Feedback added successfully",
  "data": {
    "request_id": "65f1234567890abcdef12348",
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }
}

Feedback Categories

Use the category field to classify your feedback:

Positive

Use positive for high ratings (4-5) and appreciation. Reinforces desired behaviors and builds reviewer confidence.

Constructive

Use constructive for moderate ratings (2-4) with specific improvement suggestions. Educational and growth-oriented feedback.

Issue

Use issue for low ratings (1-2) that identify problems. May require follow-up. Use sparingly for serious issues.

Feedback Best Practices

Effective Feedback Structure

Be Specific

Good: “The analysis was thorough and covered all the key policy violations I mentioned in the request.”Avoid: “Good job.”Why: Specific feedback helps reviewers understand exactly what they did well.

Balance Appreciation and Improvement

Good: “Great attention to detail in identifying spam patterns. For future requests, could you also mention the confidence level of your assessment?”Avoid: “Everything was perfect” or “Everything was wrong.”Why: Balanced feedback encourages growth while recognizing strengths.

Focus on Behavior, Not Person

Good: “The response could benefit from more detailed examples to support the conclusion.”Avoid: “You’re not very thorough.”Why: Focus on actions and outcomes rather than personal characteristics.

Include Context

Good: “Given the urgent nature of this content moderation request, the 15-minute response time was exactly what we needed.”Avoid: “Too slow.”Why: Context helps reviewers understand the specific requirements of different request types.

Feedback Analytics

Track Feedback Patterns

Monitor your feedback trends to improve request quality:

def analyze_feedback_patterns():
    """Analyze feedback patterns across all requests"""
    
    # Get all completed requests
    response = requests.get(
        "https://api.hitl.sh/v1/api/requests?status=completed&limit=100",
        headers={"Authorization": "Bearer your_api_key_here"}
    )
    
    completed_requests = response.json()["data"]["requests"]
    
    # Analyze feedback patterns (this would require additional API endpoints)
    feedback_stats = {
        "total_requests": len(completed_requests),
        "feedback_given": 0,
        "avg_rating": 0,
        "common_tags": {},
        "category_breakdown": {"positive": 0, "constructive": 0, "issue": 0},
        "reviewer_performance": {}
    }
    
    # Note: In a real implementation, you'd need endpoints to retrieve 
    # feedback data to perform this analysis
    
    return feedback_stats

def generate_feedback_suggestions(request_data, response_quality):
    """Generate feedback suggestions based on request and response analysis"""
    
    suggestions = {
        "recommended_rating": 3,
        "suggested_tags": [],
        "feedback_template": "",
        "category": "constructive"
    }
    
    # Analyze response time
    response_time = request_data.get("response_time_seconds", 0)
    if response_time < 300:  # Under 5 minutes
        suggestions["suggested_tags"].append("quick")
        suggestions["recommended_rating"] += 1
    elif response_time > 3600:  # Over 1 hour
        suggestions["feedback_template"] += "Consider faster response times for future requests. "
    
    # Analyze priority handling
    if request_data["priority"] == "critical" and response_time < 600:
        suggestions["suggested_tags"].append("urgent-handling")
        suggestions["recommended_rating"] += 1
    
    # Generate template
    if suggestions["recommended_rating"] >= 4:
        suggestions["category"] = "positive"
        suggestions["feedback_template"] = "Great work! " + suggestions["feedback_template"]
    elif suggestions["recommended_rating"] <= 2:
        suggestions["category"] = "issue"
        suggestions["feedback_template"] = "There are some areas for improvement: " + suggestions["feedback_template"]
    
    return suggestions

Bulk Feedback Operations

Provide feedback on multiple completed requests:

async function bulkFeedback(requestFeedbackPairs, options = {}) {
    const { delay = 200, validateFirst = true } = options;
    const results = [];
    
    for (const { requestId, feedback } of requestFeedbackPairs) {
        try {
            if (validateFirst) {
                // Get request details to ensure it's completed
                const requestResponse = await axios.get(
                    `https://api.hitl.sh/v1/api/requests/${requestId}`,
                    { headers: { 'Authorization': 'Bearer your_api_key_here' } }
                );
                
                const requestData = requestResponse.data.data.request;
                
                if (requestData.status !== 'completed') {
                    results.push({
                        requestId,
                        success: false,
                        error: `Request status is '${requestData.status}', not 'completed'`
                    });
                    continue;
                }
            }
            
            // Submit feedback
            const feedbackResponse = await axios.post(
                `https://api.hitl.sh/v1/api/requests/${requestId}/feedback`,
                { feedback },
                { headers: { 'Authorization': 'Bearer your_api_key_here', 'Content-Type': 'application/json' } }
            );
            
            results.push({
                requestId,
                success: true,
                feedbackId: feedbackResponse.data.data.feedback_id
            });
            
            // Rate limiting delay
            if (delay > 0) {
                await new Promise(resolve => setTimeout(resolve, delay));
            }
            
        } catch (error) {
            results.push({
                requestId,
                success: false,
                error: error.response?.data?.msg || error.message
            });
        }
    }
    
    return {
        total: requestFeedbackPairs.length,
        successful: results.filter(r => r.success).length,
        failed: results.filter(r => !r.success).length,
        results
    };
}

// Usage
const feedbackBatch = [
    {
        requestId: '65f1234567890abcdef12348',
        feedback: { rating: 5, comment: 'Excellent work!', category: 'positive' }
    },
    {
        requestId: '65f1234567890abcdef12349', 
        feedback: { rating: 4, comment: 'Good job, could be more detailed', category: 'constructive' }
    }
];

const results = await bulkFeedback(feedbackBatch);
console.log(`Submitted feedback for ${results.successful}/${results.total} requests`);

Feedback Templates

Pre-built Feedback Templates

Create reusable feedback templates for common scenarios:

Excellent Performance Template

{
  "rating": 5,
  "comment": "Outstanding work! Response was accurate, timely, and exceeded expectations. The detailed analysis and clear recommendations were exactly what we needed.",
  "accuracy": 5,
  "timeliness": 5,
  "helpfulness": 5,
  "would_recommend": true,
  "tags": ["excellent", "thorough", "professional"],
  "category": "positive"
}

Good with Minor Improvements Template

{
  "rating": 4,
  "comment": "Solid work overall. The analysis was accurate and helpful. For future requests, consider providing more specific examples to support your conclusions.",
  "accuracy": 5,
  "timeliness": 4,
  "helpfulness": 4,
  "would_recommend": true,
  "tags": ["accurate", "could-add-examples"],
  "category": "constructive"
}

Needs Improvement Template

{
  "rating": 2,
  "comment": "The response addressed the basic question but lacked the depth and detail specified in the request. Please review the requirements more carefully for future requests.",
  "accuracy": 3,
  "timeliness": 3,
  "helpfulness": 2,
  "would_recommend": false,
  "tags": ["incomplete", "needs-detail"],
  "category": "issue",
  "follow_up_needed": true
}

Quick Appreciation Template

{
  "rating": 5,
  "comment": "Perfect response! Quick, accurate, and exactly what we needed. Thank you!",
  "timeliness": 5,
  "would_recommend": true,
  "tags": ["quick", "accurate"],
  "category": "positive"
}

Access Control

Feedback Permissions

Request Creators Only

Only the API key that created the request can provide feedback on it.

Completed Requests Only

Feedback can only be added to requests with status “completed”.

One Feedback Per Request

Currently, each request can receive one feedback entry. Future versions may support multiple feedback entries or feedback updates.

Error Handling

Common Error Scenarios

Request Not Completed

{
  "error": true,
  "msg": "Feedback can only be added to completed requests"
}

Cause: Request status is not “completed”. Solution: Wait for request completion or check request status.

Invalid Rating Values

{
  "error": true,
  "msg": "Rating values must be between 1 and 5"
}

Cause: Rating fields contain values outside the 1-5 range. Solution: Ensure all rating fields are integers between 1 and 5.

Comment Too Long

{
  "error": true,
  "msg": "Comment exceeds maximum length of 1000 characters"
}

Cause: Feedback comment is longer than 1000 characters. Solution: Shorten the comment or split into multiple sentences.

Request Not Found

{
  "error": true,
  "msg": "Request not found"
}

Cause: Invalid request ID or request doesn’t belong to your API key. Solution: Verify the request ID and ownership.

Impact of Feedback

On Reviewers

Performance Insights

Feedback helps reviewers understand what works well and what needs improvement in their review process.

Motivation and Recognition

Positive feedback boosts reviewer motivation and recognizes good work.

Skill Development

Constructive feedback provides specific areas for improvement and learning opportunities.

Quality Standards

Consistent feedback helps establish and maintain quality standards across the reviewer team.

On System Quality

Improved Matching

Feedback data can be used to better match requests with appropriate reviewers based on past performance.

Quality Metrics

Aggregate feedback provides insights into overall system performance and areas for improvement.

Process Optimization

Feedback patterns help identify bottlenecks and optimization opportunities in the review process.

Next Steps

View Request History

Review your request history and identify requests that could benefit from feedback.

Reviewer Guidelines

Learn how reviewers see and respond to feedback on the mobile app.

WebhooksReceive real-time notifications when requests are completed using callback URLs. Configure callbacks on a per-request basis for instant updates.

curl -X POST https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348/feedback \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }'

{
  "error": false,
  "msg": "Feedback added successfully",
  "data": {
    "request_id": "65f1234567890abcdef12348",
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }
}

Documentation Index

​Authentication

​Path Parameters

​Body Parameters

​Feedback Object Structure

​Response

​Feedback Categories

Positive

Constructive

Issue

​Feedback Best Practices

​Effective Feedback Structure

​Feedback Analytics

​Track Feedback Patterns

​Bulk Feedback Operations

​Feedback Templates

​Pre-built Feedback Templates

​Access Control

​Feedback Permissions

​Error Handling

​Common Error Scenarios

​Impact of Feedback

​On Reviewers

​On System Quality

​Next Steps

View Request History

Reviewer Guidelines

Authentication

Path Parameters

Body Parameters

Feedback Object Structure

Response

Feedback Categories

Feedback Best Practices

Effective Feedback Structure

Feedback Analytics

Track Feedback Patterns

Bulk Feedback Operations

Feedback Templates

Pre-built Feedback Templates

Access Control

Feedback Permissions

Error Handling

Common Error Scenarios

Impact of Feedback

On Reviewers

On System Quality

Next Steps