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

# API Reference

> Complete API documentation for HITL.sh. Integrate human oversight into your AI workflows with our RESTful API.

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

```bash theme={null}
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:**

```json theme={null}
{
  "error": false,
  "msg": "Operation completed successfully",
  "data": {
    // Response data
  }
}
```

**Error Response:**

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

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

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

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

<CardGroup cols={2}>
  <Card title="Single Select" icon="list" href="/responses/single-select">
    User chooses one option from a list.
  </Card>

  <Card title="Multi Select" icon="check-square" href="/responses/multi-select">
    User chooses multiple options from a list.
  </Card>

  <Card title="Rating" icon="star" href="/responses/rating">
    User provides a numerical rating within a range.
  </Card>

  <Card title="Text" icon="type" href="/responses/text">
    User provides free-form text response.
  </Card>

  <Card title="Number" icon="hash" href="/responses/number">
    User provides a numerical value.
  </Card>
</CardGroup>

### Processing Types

<CardGroup cols={2}>
  <Card title="Time-Sensitive" icon="clock">
    Requires immediate attention with specified timeout. `timeout_seconds` required.
  </Card>

  <Card title="Deferred" icon="calendar">
    Can be processed within a longer timeframe (default: 30 days).
  </Card>
</CardGroup>

## Webhook Integration

Set up webhooks to receive real-time notifications when requests are completed:

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

```json theme={null}
{
  "error": true,
  "msg": "API key request limit exceeded",
  "data": {
    "usage_count": 100,
    "usage_limit": 100,
    "remaining": 0
  }
}
```

**Validation error:**

```json theme={null}
{
  "error": true,
  "msg": "Validation failed",
  "data": "timeout_seconds is required for time-sensitive requests"
}
```

**Access denied:**

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

<CardGroup cols={2}>
  <Card title="API Status" icon="activity" href="https://status.hitl.sh">
    Check real-time API health and uptime.
  </Card>

  <Card title="Community" icon="users" href="https://discord.gg/jYVrpmnMP9">
    Join our Discord community for support.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/hitl-sh">
    Explore our open source projects.
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@hitl.sh">
    Get help from our support team.
  </Card>
</CardGroup>

## Next Steps

<Card title="Authentication Guide" icon="key" href="/api-reference/authentication">
  Learn about API keys and security best practices.
</Card>

<Card title="Create Your First Loop" icon="plus" href="/api-reference/loops/create-loop">
  Start by creating a loop to organize your human reviewers.
</Card>

<Card title="Webhooks & Callbacks" icon="webhook" href="/api-reference/webhooks">
  Use callback URLs to receive notifications when requests complete.
</Card>