​
Get started in minutes

Add human supervision to your AI agents with HITL.sh. This guide will walk you through setting up your first review workflow.

​
Prerequisites

  • A HITL.sh account (sign up here)
  • Basic knowledge of your chosen integration method
  • An AI workflow or application that needs human oversight

​
Step 1: Create a review template

Start by creating a template that defines what content will be reviewed and what input you need from humans.

Template Editor

Learn more about creating custom review templates with our no-code editor.

​
Basic template example

{
  "name": "Content Review",
  "fields": [
    {
      "name": "content",
      "type": "text",
      "label": "Content to review",
      "required": true
    },
    {
      "name": "approval",
      "type": "boolean",
      "label": "Approve content",
      "required": true
    },
    {
      "name": "feedback",
      "type": "text",
      "label": "Feedback or comments",
      "required": false
    }
  ]
}

​
Step 2: Integrate with your workflow

Choose your preferred integration method to send review requests to HITL.sh.

​
Python SDK

from hitl import HITLClient

# Initialize client
client = HITLClient(api_key="your_api_key")

# Create review request
review = client.create_review(
    template_id="template_123",
    content={
        "content": "AI-generated article content...",
        "metadata": {"source": "gpt-4", "topic": "technology"}
    },
    assignees=["reviewer@company.com"]
)

print(f"Review created: {review.id}")

​
TypeScript SDK

import { HITLClient } from '@hitl/typescript';

// Initialize client
const client = new HITLClient({ apiKey: 'your_api_key' });

// Create review request
const review = await client.createReview({
  templateId: 'template_123',
  content: {
    content: 'AI-generated article content...',
    metadata: { source: 'gpt-4', topic: 'technology' }
  },
  assignees: ['reviewer@company.com']
});

console.log(`Review created: ${review.id}`);

​
HTTP API

curl -X POST https://api.hitl.sh/v1/reviews \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "template_123",
    "content": {
      "content": "AI-generated article content...",
      "metadata": {"source": "gpt-4", "topic": "technology"}
    },
    "assignees": ["reviewer@company.com"]
  }'

​
Step 3: Handle the review process

Once a review is created, reviewers can access it through:
  • Agent Inbox: Centralized dashboard for all pending reviews
  • Direct links: Email or Slack notifications with review links
  • Mobile app: Review on-the-go with our mobile-first interface

Agent Inbox

Learn more about managing reviews in the Agent Inbox.

​
Step 4: Process the result

When a review is completed, HITL.sh sends the result to your workflow via webhook.

​
Webhook endpoint example

from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.json
    
    if data['event'] == 'review.completed':
        review_id = data['review']['id']
        result = data['review']['result']
        
        # Process the review result
        if result['approval']:
            # Continue with approved content
            process_approved_content(result['content'])
        else:
            # Handle rejected content
            handle_rejected_content(result['feedback'])
    
    return {'status': 'ok'}, 200

​
Webhook payload structure

{
  "event": "review.completed",
  "review": {
    "id": "rev_123",
    "template_id": "template_123",
    "result": {
      "approval": true,
      "content": "AI-generated article content...",
      "feedback": "Great content, approved with minor edits"
    },
    "completed_at": "2024-01-15T10:30:00Z"
  }
}

​
Step 5: Advanced features

Once you have the basics working, explore these advanced features:

Retry Loops

Enable reviewers to request AI regeneration of content with modified prompts.

Workflow Navigation

Link multiple review steps together with metadata and navigation controls.

Custom Notifications

Configure email, Slack, and custom notification channels.

Team Management

Organize reviewers into teams with role-based permissions.

​
Next steps

Explore integrations

Discover all available integration methods and frameworks.

View examples

See real-world examples and use cases for inspiration.

API reference

Complete API documentation for custom integrations.

​
Need help?