Create Request

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

import requests

# Replace with your actual values
API_KEY = "YOUR_API_KEY"
LOOP_ID = "YOUR_LOOP_ID"

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{LOOP_ID}/requests",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "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"
    }
)

print(response.json())

const axios = require('axios');

// Replace with your actual values
const API_KEY = 'YOUR_API_KEY';
const LOOP_ID = 'YOUR_LOOP_ID';

const response = await axios.post(
  `https://api.hitl.sh/v1/api/loops/${LOOP_ID}/requests`,
  {
    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'
  },
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

console.log(response.data);

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

✏️ Editable Draft

Send an AI-generated draft for a human to polish before delivery. Perfect for notifications, emails, or any message that benefits from a final human touch.

{
  "processing_type": "time-sensitive",
  "type": "markdown",
  "priority": "medium",
  "request_text": "Please review and edit this AI-generated client notification before it is sent.",
  "timeout_seconds": 3600,
  "response_type": "editable_text",
  "response_config": {
    "draft_text": "Dear Client,\n\nYour project milestone has been completed ahead of schedule. Our team will reach out shortly to discuss next steps.\n\nBest regards,\nThe Team",
    "placeholder": "Edit the message above...",
    "min_length": 20,
    "max_length": 2000,
    "required": true
  },
  "default_response": "Notification not reviewed within timeout period",
  "platform": "api"
}

Authentication

string

required

Your API key for authentication

Path Parameters

string

required

The ID of the loop where the request will be created

Body Parameters

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.

string

required

Content type of the request
Options: markdown, image, file, video, audio

string

required

Priority level of the request
Options: low, medium, high, critical

string

required

The main content of the request (1-2000 characters)

string

URL of the image to review (required when type is image)

string[]

Array of image URLs for multi-image requests

string

URL of the document to review (required when type is file)

string

MIME type of the document, e.g. application/pdf (required when type is file)

string

Display name shown to reviewers (required when type is file)

string[]

Array of document URLs for multi-document requests

string[]

MIME types for each document in file_urls

string[]

Display names for each document in file_urls

string

URL of the video to review (required when type is video)

string[]

Array of video URLs for multi-video requests

string

URL of the audio to review (required when type is audio)

string[]

Array of audio URLs for multi-audio requests

object

Additional context data for the request (any valid JSON object)

integer

Timeout in seconds (60-86400)

Optional for: deferred requests (default: 30 days)

string

required

Type of response expected from reviewers
Options: text, editable_text, single_select, multi_select, rating, number

object

required

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

required

Default response value if timeout occurs

string

required

Platform creating the request
Options: n8n, zapier, web_portal, api, mobile, webhook

string

Version of the platform used

string

URL to call when request is completed (webhook)

Response

boolean

Whether an error occurred

string

Success message

object

Show data

string

ID of the created request

string

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

string

Processing urgency type

string

Content type of the request

string

Priority level of the request

string

ISO timestamp when the request times out

integer

Number of users who received the request notification

integer

Number of successful push notifications sent

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

import requests

# Replace with your actual values
API_KEY = "YOUR_API_KEY"
LOOP_ID = "YOUR_LOOP_ID"

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{LOOP_ID}/requests",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "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"
    }
)

print(response.json())

const axios = require('axios');

// Replace with your actual values
const API_KEY = 'YOUR_API_KEY';
const LOOP_ID = 'YOUR_LOOP_ID';

const response = await axios.post(
  `https://api.hitl.sh/v1/api/loops/${LOOP_ID}/requests`,
  {
    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'
  },
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

console.log(response.data);

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

✏️ Editable Draft

For AI-generated messages that need human review and revision before sending.

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": "Please review and edit this AI-generated client notification before it is sent.",
    "timeout_seconds": 3600,
    "response_type": "editable_text",
    "response_config": {
      "draft_text": "Dear Client,\n\nYour project milestone has been completed ahead of schedule. Our team will reach out shortly to discuss next steps.\n\nBest regards,\nThe Team",
      "placeholder": "Edit the message above...",
      "min_length": 20,
      "max_length": 2000,
      "required": true
    },
    "default_response": "Notification not reviewed within timeout period",
    "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"
  }'

import requests

# Replace with your actual values
API_KEY = "YOUR_API_KEY"
LOOP_ID = "YOUR_LOOP_ID"

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{LOOP_ID}/requests",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "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"
    }
)

print(response.json())

const axios = require('axios');

// Replace with your actual values
const API_KEY = 'YOUR_API_KEY';
const LOOP_ID = 'YOUR_LOOP_ID';

const response = await axios.post(
  `https://api.hitl.sh/v1/api/loops/${LOOP_ID}/requests`,
  {
    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'
  },
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

console.log(response.data);

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

Getting Started

Loops

Requests

Webhooks

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

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