POST
/
v1
/
loops
/
{loopId}
/
requests
curl -X POST https://api.hitl.sh/v1/loops/65f1234567890abcdef12345/requests \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "high",
    "request_text": "Please review this user-generated content for community guidelines compliance. The content has been flagged by our automated system.",
    "context": {
      "user_id": "user123",
      "post_id": "post456",
      "automated_flags": ["potential_spam"]
    },
    "timeout_seconds": 3600,
    "response_type": "single_select",
    "response_config": {
      "options": ["Approve", "Reject", "Needs Changes"]
    },
    "default_response": "Approve",
    "platform": "api",
    "platform_version": "1.0.0",
    "callback_url": "https://example.com/webhook/response"
  }'

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

​
Authentication

​
Authorization
string
required
Your API key for authentication

​
Path Parameters

​
loopId
string
required
The ID of the loop where the request will be created

​
Body Parameters

​
processing_type
string
required
Processing urgency type
Options: time-sensitive, deferred
Note: timeout_seconds is required for time-sensitive requests
​
type
string
required
Content type of the request
Options: markdown, image
​
priority
string
required
Priority level of the request
Options: low, medium, high, critical
​
request_text
string
required
The main content of the request (1-2000 characters)
​
image_url
string
URL of the image to review (required when type is image)
​
context
object
Additional context data for the request (any valid JSON object)
​
timeout_seconds
integer
Timeout in seconds (60-86400)
Required for: time-sensitive requests
Optional for: deferred requests (default: 30 days)
​
response_type
string
required
Type of response expected from reviewers
Options: text, single_select, multi_select, rating, number, boolean
​
response_config
object
required
Configuration for the response type (varies by response_type)
​
default_response
object
required
Default response if timeout occurs
​
platform
string
required
Platform creating the request
Options: n8n, zapier, web_portal, api, mobile, webhook
​
platform_version
string
Version of the platform used
​
callback_url
string
URL to call when request is completed (webhook)

​
Response

​
error
boolean
Whether an error occurred
​
msg
string
Success message
​
data
object

​
Response Type Configurations

​
Single Select

{
  "response_config": {
    "options": ["Approve", "Reject", "Needs Changes"]
  },
  "default_response": "Approve"
}

​
Multi Select

{
  "response_config": {
    "options": ["Policy Violation", "Spam", "Inappropriate Content", "Copyright"]
  },
  "default_response": ["Policy Violation"]
}

​
Rating

{
  "response_config": {
    "min": 1,
    "max": 5
  },
  "default_response": 3
}

​
Number

{
  "response_config": {
    "min": 0,
    "max": 100
  },
  "default_response": 50
}

​
Boolean

{
  "response_config": {},
  "default_response": true
}

​
Text

{
  "response_config": {},
  "default_response": "No issues found"
}

curl -X POST https://api.hitl.sh/v1/loops/65f1234567890abcdef12345/requests \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "high",
    "request_text": "Please review this user-generated content for community guidelines compliance. The content has been flagged by our automated system.",
    "context": {
      "user_id": "user123",
      "post_id": "post456",
      "automated_flags": ["potential_spam"]
    },
    "timeout_seconds": 3600,
    "response_type": "single_select",
    "response_config": {
      "options": ["Approve", "Reject", "Needs Changes"]
    },
    "default_response": "Approve",
    "platform": "api",
    "platform_version": "1.0.0",
    "callback_url": "https://example.com/webhook/response"
  }'

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

​
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": {
    "min": 1,
    "max": 5
  },
  "default_response": 3,
  "platform": "api"
}

​
Request Lifecycle

  1. Creation - Request is created and assigned a unique ID
  2. Broadcasting - Push notifications sent to all active loop members
  3. Pending - Waiting for a reviewer to claim and respond
  4. Claimed - A reviewer has started working on the request
  5. Completed - Reviewer has submitted their response
  6. Webhook - 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.