Skip to main content
POST
/
v1
/
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"
    },
    "feedback_id": "65f1234567890abcdef12355",
    "submitted_at": "2024-03-15T12:30:00Z",
    "reviewer_notified": true
  }
}
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

id
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)
feedback.would_recommend
boolean
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
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_id": "65f1234567890abcdef12355",
    "submitted_at": "2024-03-15T12:30:00Z",
    "reviewer_notified": true
  }
}

Feedback Categories

Positive

Category: positive
  • High ratings (4-5)
  • Appreciation for good work
  • Reinforces desired behaviors
  • Builds reviewer confidence

Constructive

Category: constructive
  • Moderate ratings (2-4)
  • Specific improvement suggestions
  • Educational feedback
  • Growth-oriented

Issue

Category: issue
  • Low ratings (1-2)
  • Identifies problems
  • May require follow-up
  • Used sparingly for serious issues

Feedback Best Practices

Effective Feedback Structure

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.
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.
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.
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:
{
  "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"
}
{
  "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"
}
{
  "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
}
{
  "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

Only the API key that created the request can provide feedback on it.
Feedback can only be added to requests with status “completed”.
Currently, each request can receive one feedback entry. Future versions may support multiple feedback entries or feedback updates.

Error Handling

Common Error Scenarios

{
  "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.
{
  "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.
{
  "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.
{
  "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

Feedback helps reviewers understand what works well and what needs improvement in their review process.
Positive feedback boosts reviewer motivation and recognizes good work.
Constructive feedback provides specific areas for improvement and learning opportunities.
Consistent feedback helps establish and maintain quality standards across the reviewer team.

On System Quality

Feedback data can be used to better match requests with appropriate reviewers based on past performance.
Aggregate feedback provides insights into overall system performance and areas for improvement.
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.

Loop Analytics

See how feedback is improving your loop performance over time.

Reviewer Guidelines

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