Create Request - Human in the Loop

POST

api

loops

{loopId}

requests

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

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

⭐ Quality Rating

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

💬 Detailed Feedback

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

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

When processing_type is set to "time-sensitive", the timeout_seconds parameter becomes required. Time-sensitive requests must specify an explicit timeout.

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)

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

response_config

object

required

Configuration for the response type (varies by response_type)
Response Types Guide

default_response

required

Default response value 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

Show data

request_id

string

ID of the created request

status

string

Current status of the request (always “pending” on creation)

processing_type

string

Processing urgency type

type

string

Content type of the request

priority

string

Priority level of the request

timeout_at

string

ISO timestamp when the request times out

broadcasted_to

integer

Number of users who received the request notification

notifications_sent

integer

Number of successful push notifications sent

polling_url

string

URL for polling request status

Response Type Quick Reference

For complete configuration options and advanced examples, visit the Response Types Guide.

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_max": 5
  },
  "default_response": 3
}

Note: Only scale_max is required. Optional fields with defaults:

scale_min: defaults to 1
scale_step: defaults to 1
required: defaults to false

Number - Numeric Input

{
  "response_config": {
    "max_value": 100
  },
  "default_response": 50
}

Note: Only max_value is required. Optional fields with defaults:

min_value: defaults to 1
decimal_places: defaults to 2
allow_negative: defaults to false
required: defaults to false

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

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

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

⭐ Rating Scale

For quality ratings and scores.

cURL

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

🔢 Number Input

For quantities, counts, or measurements.

cURL

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": "How many errors do you count?",
    "timeout_seconds": 1800,
    "response_type": "number",
    "response_config": {
      "max_value": 100,
      "min_value": 0,
      "decimal_places": 0
    },
    "default_response": 0,
    "platform": "api"
  }'

✍️ Text Response

For detailed feedback and explanations.

cURL

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": "single_select",
  "response_config": {
    "options": ["Approve", "Reject"]
  },
  "default_response": "Reject",
  "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 ID
Broadcasting - Push notifications sent to all active loop members
Pending - Waiting for a reviewer to respond
Completed - Reviewer has submitted their response
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.

Get User RequestsRetrieve all requests created by your API key with status, response data, and performance metrics

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 Start for Common Use Cases

​Authentication

​Path Parameters

​Body Parameters

​Response

​Response Type Quick Reference

​Single Select - Choose One Option

​Multi Select - Choose Multiple Options

​Rating - Numeric Scale

​Number - Numeric Input

​Text - Free Form Input

Need More Details?

​Quick Test Examples

​Use Cases

​Content Moderation

​Image Review

​Quality Rating

​Request Lifecycle

​Next Steps

Poll Request Status

Set Up Webhooks

Cancel Request

Quick Start for Common Use Cases

Authentication

Path Parameters

Body Parameters

Response

Response Type Quick Reference

Single Select - Choose One Option

Multi Select - Choose Multiple Options

Rating - Numeric Scale

Number - Numeric Input

Text - Free Form Input

Quick Test Examples

Use Cases

Content Moderation

Image Review

Quality Rating

Request Lifecycle

Next Steps