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

# Quickstart Guide

> Get started with HITL.sh in under 10 minutes. Build your first human-in-the-loop workflow with step-by-step instructions.

Build your first HITL (Human-in-the-Loop) workflow in under 10 minutes. This tutorial walks you through creating a content moderation workflow where human reviewers evaluate user-generated content.

> [!NOTE]
>
> **What You'll Build**: A content moderation workflow that receives flagged content via webhook, routes it to human reviewers, and returns their decision.

## Prerequisites

> [card] HITL.sh Account
>
> [Sign up for free](https://hitl.sh/signup) and get your API key from the dashboard.

> [card] Development Environment
>
> Python 3.7+, Node.js 16+, or your preferred language with HTTP client support.

## Step 1: Get Your API Key

**1. Sign Up**

Create your free account at [hitl.sh/signup](https://hitl.sh/signup)

**2. Generate API Key**

Go to your dashboard and create a new API key. Copy and save it securely.

**3. Test Connection**

Verify your API key works using the dedicated test endpoint:

```bash theme={null}
curl -X GET https://api.hitl.sh/v1/test \
  -H "Authorization: Bearer your_api_key_here"
```

You should get a JSON response confirming your API key is valid.

## Step 2: Create a Workflow

A **workflow** is a visual pipeline that routes data through processing steps, including human review. Create one in the dashboard:

**1. Open the Dashboard**

Navigate to [my.hitl.sh](https://my.hitl.sh) and sign in.

**2. Create a New Workflow**

Click **Workflows** in the sidebar, then click **New Workflow**. Name it "Content Moderation".

**3. Add a Human Review Node**

In the workflow designer canvas, click the **+** button on the Trigger node and add a **Human Review** node. Configure it:

* **Response type**: Single Select
* **Options**: Approve, Reject, Escalate
* **Reviewers**: Select your Universe (all reviewers) or a specific group
* **Timeout**: 3600 seconds (1 hour)
* **Default response**: Reject

**4. Activate the Workflow**

Click **Save**, then toggle **Activate**. Copy the webhook URL displayed at the top of the designer.

## Step 3: Add Reviewers

Your workflow needs human reviewers to respond. Add people in the **Humans** section of the dashboard:

**1. Navigate to Humans**

Click **Humans** in the sidebar.

**2. Add People**

Click **Add Person** and invite reviewers by email. They will receive an invitation to join HITL.sh.

**3. Download the Mobile App**

Reviewers download the HITL.sh mobile app ([App Store](https://apps.apple.com/us/app/hitl-human-in-the-loop/id6752878072) | [Google Play](https://play.google.com/store/apps/details?id=hitl.sh.app)) and sign in to receive push notifications.

> [!NOTE]
>
> **For Testing**: You can test by adding yourself as a reviewer and responding via the web dashboard inbox or the mobile app.

## Step 4: Trigger the Workflow

Send a POST request to your workflow's webhook URL to start an execution:

> [tab] Python
>
> ```python theme={null}
> import requests
>
> webhook_url = "https://api.hitl.sh/v1/workflows/YOUR_WORKFLOW_ID/trigger"
> headers = {
>     "Authorization": "Bearer YOUR_API_KEY",
>     "Content-Type": "application/json"
> }
> payload = {
>     "content": "Please review this user comment: 'Great product, highly recommend! Check my link for a discount.'",
>     "user_id": "user_123",
>     "category": "comment"
> }
>
> response = requests.post(webhook_url, headers=headers, json=payload)
> execution = response.json()
>
> print(f"Execution started: {execution['data']['execution_id']}")
> ```

> [tab] Node.js
>
> ```javascript theme={null}
> const axios = require('axios');
>
> const webhookUrl = 'https://api.hitl.sh/v1/workflows/YOUR_WORKFLOW_ID/trigger';
> const headers = {
>   'Authorization': 'Bearer YOUR_API_KEY',
>   'Content-Type': 'application/json'
> };
> const payload = {
>   content: "Please review this user comment: 'Great product, highly recommend! Check my link for a discount.'",
>   user_id: 'user_123',
>   category: 'comment'
> };
>
> const response = await axios.post(webhookUrl, payload, { headers });
> console.log('Execution started:', response.data.data.execution_id);
> ```

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST https://api.hitl.sh/v1/workflows/YOUR_WORKFLOW_ID/trigger \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "content": "Please review this user comment: Great product, highly recommend!",
>     "user_id": "user_123",
>     "category": "comment"
>   }'
> ```

## Step 5: Respond and View Results

1. Reviewers receive a push notification on the mobile app
2. Open the review request, read the content, and select a response (Approve, Reject, or Escalate)
3. The workflow execution completes

View the result in the **Executions** tab of the workflow designer, or poll the execution status via API:

```python theme={null}
execution_id = "exec_abc123"
status_url = f"https://api.hitl.sh/v1/executions/{execution_id}"
response = requests.get(status_url, headers=headers)
result = response.json()

print(f"Status: {result['data']['status']}")
print(f"Response: {result['data']['response_data']}")
```

## What's Next?

> [card] [Workflow Designer](https://docs.hitl.sh/guides/workflow-designer.md)
>
> Learn about all node types, canvas controls, and advanced configuration.

> [card] [Response Types](https://docs.hitl.sh/responses/types.md)
>
> Explore all seven response types and their configurations.

> [card] [Mobile App Guide](https://docs.hitl.sh/mobile/overview.md)
>
> Learn how reviewers use the mobile app to respond.

> [card] [Integrations](https://docs.hitl.sh/integrations/overview.md)
>
> Connect your workflows to n8n, Zapier, Make, and more.

> [card] [SDKs](https://docs.hitl.sh/sdks.md)
>
> Use our official SDKs for easier integration.

> [card] [Humans](https://docs.hitl.sh/concepts/humans.md)
>
> Set up reviewer groups for targeted assignment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.