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

# Add Request Feedback

> Provide feedback on completed requests to improve reviewer performance and system quality over time

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`

**data**

**request\_id** `string`

ID of the request that received feedback

**feedback** `object`

The feedback object that was submitted

```bash cURL theme={null}
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"
    }
  }'
```

```python Python theme={null}
import requests

def add_request_feedback(request_id, feedback_data):
    """Add comprehensive feedback to a completed request"""
    
    url = f"https://api.hitl.sh/v1/api/requests/{request_id}/feedback"
    headers = {
        "Authorization": "Bearer your_api_key_here",
        "Content-Type": "application/json"
    }
    
    # Validate feedback data
    if "rating" in feedback_data:
        if not (1 <= feedback_data["rating"] <= 5):
            raise ValueError("Rating must be between 1 and 5")
    
    if "comment" in feedback_data:
        if len(feedback_data["comment"]) > 1000:
            raise ValueError("Comment must be 1000 characters or less")
    
    payload = {"feedback": feedback_data}
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code == 200:
        result = response.json()
        print(f"✅ Feedback submitted successfully")
        print(f"   Feedback ID: {result['data']['feedback_id']}")
        return result
    else:
        error_msg = response.json().get("msg", "Unknown error")
        print(f"❌ Failed to submit feedback: {error_msg}")
        return {"error": True, "msg": error_msg}

# Example usage
feedback = {
    "rating": 5,
    "comment": "Excellent work! Very detailed analysis and spot-on recommendations.",
    "accuracy": 5,
    "timeliness": 4,
    "helpfulness": 5,
    "would_recommend": True,
    "tags": ["thorough", "insightful", "professional"],
    "category": "positive"
}

result = add_request_feedback("65f1234567890abcdef12348", feedback)
```

```javascript Node.js theme={null}
const axios = require('axios');

class FeedbackManager {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseURL = 'https://api.hitl.sh/v1';
    }
    
    async addFeedback(requestId, feedbackData) {
        try {
            // Validate feedback data
            this.validateFeedback(feedbackData);
            
            const response = await axios.post(
                `${this.baseURL}/requests/${requestId}/feedback`,
                { feedback: feedbackData },
                {
                    headers: {
                        'Authorization': `Bearer ${this.apiKey}`,
                        'Content-Type': 'application/json'
                    }
                }
            );
            
            console.log('✅ Feedback submitted successfully');
            return response.data;
            
        } catch (error) {
            console.error('❌ Failed to submit feedback:', error.response?.data?.msg);
            throw error;
        }
    }
    
    validateFeedback(feedback) {
        // Validate rating fields
        const ratingFields = ['rating', 'accuracy', 'timeliness', 'helpfulness'];
        ratingFields.forEach(field => {
            if (feedback[field] !== undefined) {
                if (!Number.isInteger(feedback[field]) || feedback[field] < 1 || feedback[field] > 5) {
                    throw new Error(`${field} must be an integer between 1 and 5`);
                }
            }
        });
        
        // Validate comment length
        if (feedback.comment && feedback.comment.length > 1000) {
            throw new Error('Comment must be 1000 characters or less');
        }
        
        // Validate category
        if (feedback.category) {
            const validCategories = ['positive', 'constructive', 'issue'];
            if (!validCategories.includes(feedback.category)) {
                throw new Error('Category must be one of: positive, constructive, issue');
            }
        }
    }
    
    // Helper method for quick positive feedback
    async addPositiveFeedback(requestId, comment, rating = 5) {
        return this.addFeedback(requestId, {
            rating,
            comment,
            category: 'positive',
            would_recommend: true
        });
    }
    
    // Helper method for constructive feedback
    async addConstructiveFeedback(requestId, comment, suggestions) {
        return this.addFeedback(requestId, {
            rating: 3,
            comment,
            category: 'constructive',
            tags: suggestions,
            follow_up_needed: true
        });
    }
}

// Usage
const feedbackManager = new FeedbackManager('your_api_key_here');

// Detailed feedback
await feedbackManager.addFeedback('65f1234567890abcdef12348', {
    rating: 4,
    comment: 'Good analysis but could have been more detailed in the recommendations section.',
    accuracy: 5,
    timeliness: 3,
    helpfulness: 4,
    would_recommend: true,
    tags: ['accurate', 'could-be-more-detailed'],
    category: 'constructive'
});

// Quick positive feedback
await feedbackManager.addPositiveFeedback(
    '65f1234567890abcdef12349', 
    'Perfect response, exactly what we needed!'
);
```

```json Response theme={null}
{
  "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:

> [card] Positive
>
> Use `positive` for high ratings (4-5) and appreciation. Reinforces desired behaviors and builds reviewer confidence.

> [card] Constructive
>
> Use `constructive` for moderate ratings (2-4) with specific improvement suggestions. Educational and growth-oriented feedback.

> [card] 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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:

```python theme={null}
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:

```javascript theme={null}
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:

> [accordion] Excellent Performance Template
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Good with Minor Improvements Template
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Needs Improvement Template
>
> ```json theme={null}
> {
>   "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
> }
> ```

> [accordion] Quick Appreciation Template
>
> ```json theme={null}
> {
>   "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

> [accordion] Request Creators Only
>
> Only the API key that created the request can provide feedback on it.

> [accordion] Completed Requests Only
>
> Feedback can only be added to requests with status "completed".

> [accordion] 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

> [accordion] Request Not Completed
>
> ```json theme={null}
> {
>   "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.

> [accordion] Invalid Rating Values
>
> ```json theme={null}
> {
>   "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.

> [accordion] Comment Too Long
>
> ```json theme={null}
> {
>   "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.

> [accordion] Request Not Found
>
> ```json theme={null}
> {
>   "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

> [accordion] Performance Insights
>
> Feedback helps reviewers understand what works well and what needs improvement in their review process.

> [accordion] Motivation and Recognition
>
> Positive feedback boosts reviewer motivation and recognizes good work.

> [accordion] Skill Development
>
> Constructive feedback provides specific areas for improvement and learning opportunities.

> [accordion] Quality Standards
>
> Consistent feedback helps establish and maintain quality standards across the reviewer team.

### On System Quality

> [accordion] Improved Matching
>
> Feedback data can be used to better match requests with appropriate reviewers based on past performance.

> [accordion] Quality Metrics
>
> Aggregate feedback provides insights into overall system performance and areas for improvement.

> [accordion] Process Optimization
>
> Feedback patterns help identify bottlenecks and optimization opportunities in the review process.

## Next Steps

> [card] [View Request History](https://docs.hitl.sh/api-reference/requests/get-requests.md)
>
> Review your request history and identify requests that could benefit from feedback.

> [card] [Reviewer Guidelines](https://docs.hitl.sh/mobile/responding.md)
>
> Learn how reviewers see and respond to feedback on the mobile app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.