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

# Create Request

> Create a new human review request within a loop and broadcast it to active members with push notifications

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

<AccordionGroup>
  <Accordion title="✅ Simple Approval Workflow" icon="check">
    Perfect for content moderation, document approval, or basic yes/no decisions.

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

  <Accordion title="⭐ Quality Rating" icon="star">
    Rate content quality, AI outputs, or customer service interactions.

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

  <Accordion title="💬 Detailed Feedback" icon="comment">
    Get written feedback, suggestions, or explanations from reviewers.

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

  <Accordion title="🏷️ Multi-Category Tagging" icon="tags">
    Identify multiple issues, features, or categories in content.

    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>
</AccordionGroup>

## Authentication

<ParamField header="Authorization" type="string" required>
  Your API key for authentication
</ParamField>

## Path Parameters

<ParamField path="loopId" type="string" required>
  The ID of the loop where the request will be created
</ParamField>

## Body Parameters

<ParamField body="processing_type" type="string" required>
  Processing urgency type

  <br />

  <strong>Options:</strong> `time-sensitive`, `deferred`
</ParamField>

<Warning>
  When `processing_type` is set to `"time-sensitive"`, the `timeout_seconds` parameter becomes **required**. Time-sensitive requests must specify an explicit timeout.
</Warning>

<ParamField body="type" type="string" required>
  Content type of the request

  <br />

  <strong>Options:</strong> `markdown`, `image`
</ParamField>

<ParamField body="priority" type="string" required>
  Priority level of the request

  <br />

  <strong>Options:</strong> `low`, `medium`, `high`, `critical`
</ParamField>

<ParamField body="request_text" type="string" required>
  The main content of the request (1-2000 characters)
</ParamField>

<ParamField body="image_url" type="string">
  URL of the image to review (required when `type` is `image`)
</ParamField>

<ParamField body="context" type="object">
  Additional context data for the request (any valid JSON object)
</ParamField>

<ParamField body="timeout_seconds" type="integer">
  Timeout in seconds (60-86400)

  <br />

  <strong>⚠️ REQUIRED when processing\_type is "time-sensitive"</strong>

  <br />

  <strong>Optional for:</strong> `deferred` requests (default: 30 days)
</ParamField>

<ParamField body="response_type" type="string" required>
  Type of response expected from reviewers

  <br />

  <strong>Options:</strong> `text`, `single_select`, `multi_select`, `rating`, `number`
</ParamField>

<ParamField body="response_config" type="object" required>
  Configuration for the response type (varies by response\_type)

  <br />

  <strong>📖 See examples:</strong> <a href="/responses/types">Response Types Guide</a>
</ParamField>

<ParamField body="default_response" required>
  Default response value if timeout occurs
</ParamField>

<ParamField body="platform" type="string" required>
  Platform creating the request

  <br />

  <strong>Options:</strong> `n8n`, `zapier`, `web_portal`, `api`, `mobile`, `webhook`
</ParamField>

<ParamField body="platform_version" type="string">
  Version of the platform used
</ParamField>

<ParamField body="callback_url" type="string">
  URL to call when request is completed (webhook)
</ParamField>

## Response

<ResponseField name="error" type="boolean">
  Whether an error occurred
</ResponseField>

<ResponseField name="msg" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="request_id" type="string">
      ID of the created request
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the request (always "pending" on creation)
    </ResponseField>

    <ResponseField name="processing_type" type="string">
      Processing urgency type
    </ResponseField>

    <ResponseField name="type" type="string">
      Content type of the request
    </ResponseField>

    <ResponseField name="priority" type="string">
      Priority level of the request
    </ResponseField>

    <ResponseField name="timeout_at" type="string">
      ISO timestamp when the request times out
    </ResponseField>

    <ResponseField name="broadcasted_to" type="integer">
      Number of users who received the request notification
    </ResponseField>

    <ResponseField name="notifications_sent" type="integer">
      Number of successful push notifications sent
    </ResponseField>

    <ResponseField name="polling_url" type="string">
      URL for polling request status
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Type Quick Reference

<Info>
  For complete configuration options and advanced examples, visit the [Response Types Guide](/responses/types).
</Info>

### Single Select - Choose One Option

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

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

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

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

```json theme={null}
{
  "response_config": {},
  "default_response": "No issues found"
}
```

<Card title="Need More Details?" icon="book-open" href="/responses/types">
  Visit our complete Response Types Guide for advanced configurations, validation rules, and best practices.
</Card>

<Note>
  **Ready to test?**

  1. Get your API key from [app.hitl.sh](https://app.hitl.sh)
  2. Create a loop and copy the Loop ID
  3. Replace `YOUR_API_KEY` and `YOUR_LOOP_ID` in the examples below
  4. The request will be sent to all active members in your loop for review
</Note>

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

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</RequestExample>

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

## Quick Test Examples

Copy any of these examples to test different response types:

<AccordionGroup>
  <Accordion title="✅ Single Select (Choose One)" icon="check-circle">
    Perfect for yes/no decisions or selecting one option.

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

  <Accordion title="🏷️ Multi Select (Choose Multiple)" icon="list-check">
    For selecting multiple issues or features.

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

  <Accordion title="⭐ Rating Scale" icon="star">
    For quality ratings and scores.

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

  <Accordion title="🔢 Number Input" icon="hashtag">
    For quantities, counts, or measurements.

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

  <Accordion title="✍️ Text Response" icon="pen">
    For detailed feedback and explanations.

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

## Use Cases

### Content Moderation

Review flagged user-generated content:

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

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

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

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 respond
4. **Completed** - Reviewer has submitted their response
5. **Webhook** - Callback URL is notified (if configured)

## Next Steps

<Card title="Poll Request Status" icon="refresh" href="/api-reference/requests/get-request">
  Check the status and response of your request using the polling URL.
</Card>

<Card title="Set Up Webhooks" icon="webhook" href="/api-reference/webhooks">
  Configure webhooks to receive real-time notifications when requests complete.
</Card>

<Card title="Cancel Request" icon="x" href="/api-reference/requests/cancel-request">
  Cancel a pending request if it's no longer needed.
</Card>