Skip to main content

​
HITL.sh API Reference

The HITL.sh API provides a RESTful interface for integrating human supervision into your AI workflows. Create loops, manage requests, and route decisions to human reviewers with our comprehensive API.

​
Base URL

https://api.hitl.sh/v1

​
Authentication

Use API keys for machine-to-machine integration. Include your API key in the header: 
Authorization: Bearer your_api_key_here
Rate Limits:
  • 100 requests per hour per API key
  • Rate limit headers included in responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1642233600

​
Response Format

All API responses follow a consistent JSON format: Success Response: 
{
  "error": false,
  "msg": "Operation completed successfully",
  "data": {
    // Response data
  }
}
Error Response: 
{
  "error": true,
  "msg": "Error description",
  "data": {
    // Additional error details (optional)
  }
}

​
HTTP Status Codes

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request data or validation error
  • 401 Unauthorized: Invalid or missing authentication
  • 403 Forbidden: Access denied to resource
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

​
Core Resources

​
Loops

Loops are human review workflows that route requests to team members:
  • POST /api/loops - Create a new loop
  • GET /api/loops - Get your loops
  • GET /api/loops/{id} - Get specific loop
  • PUT /api/loops/{id} - Update loop
  • DELETE /api/loops/{id} - Delete loop
  • GET /api/loops/{id}/members - Get loop members
  • DELETE /api/loops/{id}/members/{userId} - Remove member

​
Requests

Requests are human review tasks sent to loop members:
  • POST /api/loops/{loopId}/requests - Create request in loop
  • GET /api/requests - Get your requests
  • GET /api/requests/{id} - Get specific request
  • DELETE /api/requests/{id} - Cancel request
  • POST /api/requests/{id}/feedback - Add feedback
  • GET /api/loops/{loopId}/requests - Get loop requests

​
Quick Start Example

​
1. Create a Loop

curl -X POST https://api.hitl.sh/v1/api/loops \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Content Moderation",
    "description": "Review user-generated content",
    "icon": "shield-check"
  }'

​
2. Create a Request

curl -X POST https://api.hitl.sh/v1/api/loops/LOOP_ID/requests \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "high",
    "request_text": "Please review this user comment for community guideline compliance",
    "response_type": "single_select",
    "response_config": {
      "options": [
        {
          "value": "approve",
          "label": "✅ Approve Content"
        },
        {
          "value": "reject",
          "label": "❌ Reject Content"
        },
        {
          "value": "escalate",
          "label": "🚨 Escalate for Review"
        }
      ],
      "required": true
    },
    "default_response": "reject",
    "timeout_seconds": 1800,
    "platform": "api"
  }'

​
3. Poll for Response

curl -X GET https://api.hitl.sh/v1/api/requests/REQUEST_ID \
  -H "Authorization: Bearer your_api_key_here"

​
Request Types and Response Configuration

​
Response Types

Single Select

User chooses one option from a list.

Multi Select

User chooses multiple options from a list.

Rating

User provides a numerical rating within a range.

Text

User provides free-form text response.

Number

User provides a numerical value.

​
Processing Types

Time-Sensitive

Requires immediate attention with specified timeout. timeout_seconds required.

Deferred

Can be processed within a longer timeframe (default: 30 days).

​
Webhook Integration

Set up webhooks to receive real-time notifications when requests are completed: 
{
  "event": "request.completed",
  "request_id": "65f1234567890abcdef12348",
  "status": "completed",
  "response_data": "Approve",
  "response_by": "reviewer@example.com",
  "completed_at": "2024-03-15T10:45:00Z"
}

​
Error Handling

​
Common Error Scenarios

Rate limit exceeded: 
{
  "error": true,
  "msg": "API key request limit exceeded",
  "data": {
    "usage_count": 100,
    "usage_limit": 100,
    "remaining": 0
  }
}
Validation error: 
{
  "error": true,
  "msg": "Validation failed",
  "data": "timeout_seconds is required for time-sensitive requests"
}
Access denied: 
{
  "error": true,
  "msg": "Access denied to this loop"
}

​
Best Practices

​
API Usage

  • Use HTTPS: Always use secure connections
  • Store keys securely: Never commit API keys to version control
  • Implement retries: Use exponential backoff for failed requests
  • Monitor rate limits: Track your API usage to avoid limits
  • Handle errors gracefully: Implement proper error handling

​
Request Management

  • Set appropriate timeouts: Balance urgency with reviewer availability
  • Use webhooks: More efficient than polling for status updates
  • Provide context: Include relevant metadata to help reviewers
  • Choose response types carefully: Match response type to your use case

​
SDKs and Integration

​
Official Libraries

  • Python: pip install hitl-python (coming soon)
  • Node.js: npm install @hitl/node (coming soon)
  • Go: go get github.com/hitl-sh/go-client (coming soon)

​
No-Code Integrations

  • n8n: Available in the n8n community library
  • Zapier: Connect HITL.sh to 5000+ apps
  • Make: Visual workflow automation

​
Support and Resources

API Status

Check real-time API health and uptime.

Community

Join our Discord community for support.

GitHub

Explore our open source projects.

Support

Get help from our support team.

​
Next Steps

Authentication Guide

Learn about API keys and security best practices.

Create Your First Loop

Start by creating a loop to organize your human reviewers.

Webhooks & Callbacks

Use callback URLs to receive notifications when requests complete.