Create a new request that will be sent to all active members of a loop for human review. The request supports multiple content types, response configurations, and notification systems.
Quick Start for Common Use Cases
✅ Simple Approval Workflow
Perfect for content moderation, document approval, or basic yes/no decisions. { "processing_type" : "time-sensitive" , "type" : "markdown" , "priority" : "medium" , "request_text" : "Please review this content for approval" , "timeout_seconds" : 1800 , "response_type" : "single_select" , "response_config" : { "options" : [ { "value" : "approve" , "label" : "Approve" }, { "value" : "reject" , "label" : "Reject" } ], "required" : true }, "default_response" : "reject" , "platform" : "api" }
Rate content quality, AI outputs, or customer service interactions. { "processing_type" : "time-sensitive" , "type" : "markdown" , "priority" : "low" , "request_text" : "Rate the quality of this AI response on a scale of 1-5" , "timeout_seconds" : 3600 , "response_type" : "rating" , "response_config" : { "scale_min" : 1 , "scale_max" : 5 , "scale_step" : 1 , "required" : true }, "default_response" : 3 , "platform" : "api" }
Get written feedback, suggestions, or explanations from reviewers. { "processing_type" : "deferred" , "type" : "markdown" , "priority" : "low" , "request_text" : "Provide feedback on this article draft" , "response_type" : "text" , "response_config" : { "placeholder" : "Provide your detailed feedback here..." , "min_length" : 50 , "max_length" : 1000 , "required" : true }, "default_response" : "No feedback provided" , "platform" : "api" }
🏷️ Multi-Category Tagging
Identify multiple issues, features, or categories in content. { "processing_type" : "time-sensitive" , "type" : "markdown" , "priority" : "medium" , "request_text" : "What issues do you see in this content? Select all that apply:" , "timeout_seconds" : 2400 , "response_type" : "multi_select" , "response_config" : { "options" : [ { "value" : "grammar" , "label" : "Grammar Issues" }, { "value" : "factual" , "label" : "Factual Errors" }, { "value" : "structure" , "label" : "Poor Structure" }, { "value" : "none" , "label" : "No Issues Found" } ], "min_selections" : 1 , "max_selections" : 4 , "required" : true }, "default_response" : "none" , "platform" : "api" } Authentication Your API key for authentication
Path Parameters The ID of the loop where the request will be created
Body Parameters Processing urgency type Options: time-sensitive, deferred
When processing_type is set to "time-sensitive", the timeout_seconds parameter becomes required . Time-sensitive requests must specify an explicit timeout.
Content type of the request Options: markdown, image
Priority level of the request Options: low, medium, high, critical
The main content of the request (1-2000 characters)
URL of the image to review (required when type is image)
Additional context data for the request (any valid JSON object)
Timeout in seconds (60-86400) Optional for: deferred requests (default: 30 days)
Type of response expected from reviewers Options: text, single_select, multi_select, rating, number
Default response value if timeout occurs
Platform creating the request Options: n8n, zapier, web_portal, api, mobile, webhook
Version of the platform used
URL to call when request is completed (webhook)
Response Whether an error occurred
ID of the created request
Current status of the request (always “pending” on creation)
Content type of the request
Priority level of the request
ISO timestamp when the request times out
Number of users who received the request notification
Number of successful push notifications sent
URL for polling request status
Response Type Quick Reference Single Select - Choose One Option { "response_config" : { "options" : [ { "value" : "approve" , "label" : "Approve" }, { "value" : "reject" , "label" : "Reject" }, { "value" : "needs_changes" , "label" : "Needs Changes" } ], "required" : true }, "default_response" : "reject" } Multi Select - Choose Multiple Options { "response_config" : { "options" : [ { "value" : "policy_violation" , "label" : "Policy Violation" }, { "value" : "spam" , "label" : "Spam Content" }, { "value" : "inappropriate" , "label" : "Inappropriate Content" } ], "min_selections" : 1 , "max_selections" : 3 , "required" : true }, "default_response" : "policy_violation" } Rating - Numeric Scale { "response_config" : { "scale_min" : 1 , "scale_max" : 5 , "scale_step" : 1 , "required" : true }, "default_response" : 3 } { "response_config" : { "min_value" : 0 , "max_value" : 100 , "decimal_places" : 0 , "allow_negative" : false , "required" : true }, "default_response" : 50 } Text - Free Form Input { "response_config" : {}, "default_response" : "No issues found" }
Need More Details? Visit our complete Response Types Guide for advanced configurations, validation rules, and best practices.
Ready to test?
Get your API key from app.hitl.sh
Create a loop and copy the Loop ID
Replace YOUR_API_KEY and YOUR_LOOP_ID in the examples below
The request will be sent to all active members in your loop for review
curl -X POST https://api.hitl.sh/v1/api/loops/YOUR_LOOP_ID/requests \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "processing_type": "time-sensitive", "type": "markdown", "priority": "medium", "request_text": "Please review this content", "timeout_seconds": 1800, "response_type": "single_select", "response_config": { "options": [ {"value": "approve", "label": "Approve"}, {"value": "reject", "label": "Reject"} ], "required": true }, "default_response": "reject", "platform": "api" }'
{ "error" : false , "msg" : "Request created and broadcasted successfully" , "data" : { "request_id" : "65f1234567890abcdef12348" , "status" : "pending" , "processing_type" : "time-sensitive" , "type" : "markdown" , "priority" : "high" , "timeout_at" : "2024-03-15T11:30:00Z" , "broadcasted_to" : 4 , "notifications_sent" : 3 , "polling_url" : "/v1/api/requests/65f1234567890abcdef12348" } } Quick Test Examples Copy any of these examples to test different response types:
✅ Single Select (Choose One)
Perfect for yes/no decisions or selecting one option. curl -X POST https://api.hitl.sh/v1/api/loops/YOUR_LOOP_ID/requests \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "processing_type": "time-sensitive", "type": "markdown", "priority": "medium", "request_text": "Should we approve this content?", "timeout_seconds": 1800, "response_type": "single_select", "response_config": { "options": [ {"value": "yes", "label": "Yes, approve it"}, {"value": "no", "label": "No, reject it"} ], "required": true }, "default_response": "no", "platform": "api" }'
🏷️ Multi Select (Choose Multiple)
For selecting multiple issues or features. curl -X POST https://api.hitl.sh/v1/api/loops/YOUR_LOOP_ID/requests \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "processing_type": "time-sensitive", "type": "markdown", "priority": "medium", "request_text": "What issues do you see? Select all that apply:", "timeout_seconds": 1800, "response_type": "multi_select", "response_config": { "options": [ {"value": "grammar", "label": "Grammar issues"}, {"value": "tone", "label": "Wrong tone"}, {"value": "factual", "label": "Factual errors"}, {"value": "none", "label": "No issues"} ], "min_selections": 1, "max_selections": 4, "required": true }, "default_response": "none", "platform": "api" }'
For quality ratings and scores. curl -X POST https://api.hitl.sh/v1/api/loops/YOUR_LOOP_ID/requests \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "processing_type": "time-sensitive", "type": "markdown", "priority": "medium", "request_text": "Rate this content quality (1-5 scale):", "timeout_seconds": 1800, "response_type": "rating", "response_config": { "scale_min": 1, "scale_max": 5, "scale_step": 1, "required": true }, "default_response": 3, "platform": "api" }'
For detailed feedback and explanations. curl -X POST https://api.hitl.sh/v1/api/loops/YOUR_LOOP_ID/requests \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "processing_type": "deferred", "type": "markdown", "priority": "low", "request_text": "Please provide detailed feedback:", "response_type": "text", "response_config": {}, "default_response": "No feedback provided", "platform": "api" }' Use Cases Content Moderation Review flagged user-generated content:
{ "processing_type" : "time-sensitive" , "type" : "markdown" , "priority" : "medium" , "request_text" : "Review this comment for policy violations" , "timeout_seconds" : 1800 , "response_type" : "single_select" , "response_config" : { "options" : [ "Approve" , "Remove" , "Shadow Ban" ] }, "default_response" : "Approve" , "platform" : "api" } Image Review Review images for appropriate content:
{ "processing_type" : "time-sensitive" , "type" : "image" , "priority" : "high" , "request_text" : "Review this uploaded image for inappropriate content" , "image_url" : "https://example.com/uploads/image123.jpg" , "timeout_seconds" : 900 , "response_type" : "boolean" , "response_config" : {}, "default_response" : true , "platform" : "api" } Quality Rating Rate AI-generated content quality:
{ "processing_type" : "deferred" , "type" : "markdown" , "priority" : "low" , "request_text" : "Rate the quality of this AI-generated response" , "response_type" : "rating" , "response_config" : { "scale_min" : 1 , "scale_max" : 5 , "scale_step" : 1 , "required" : true }, "default_response" : 3 , "platform" : "api" } Request Lifecycle
Creation - Request is created and assigned a unique IDBroadcasting - Push notifications sent to all active loop membersPending - Waiting for a reviewer to claim and respondClaimed - A reviewer has started working on the requestCompleted - Reviewer has submitted their responseWebhook - Callback URL is notified (if configured)
Next Steps
Poll Request Status Check the status and response of your request using the polling URL.
Set Up Webhooks Configure webhooks to receive real-time notifications when requests complete.
Cancel Request Cancel a pending request if it’s no longer needed.
