API Keys

API keys are your secure credentials for integrating HITL.sh with your applications, workflows, and third-party tools. They authenticate your requests and ensure only authorized systems can interact with your loops and data.

Understanding API Keys

API keys in HITL.sh serve as your application’s identity and provide secure access to:

Loop Management: Create, read, update, and delete loops
Request Operations: Submit requests and retrieve responses
Loop Members: Add and remove reviewers from loops
Webhook Configuration: Set up event notifications
Request Feedback: Add feedback to completed requests

Keep your API keys secure and never expose them in client-side code or public repositories. Treat them like passwords.

Generating Your First API Key

Visit my.hitl.sh and log in to your account.

Navigate to API Keys

Go to Settings → API Keys from the main navigation menu.

Create New API Key

Click the “Create New API Key” button to generate a new key.

Copy and Store Securely

Copy the generated API key immediately and store it securely in environment variables. The key is only shown once for security reasons.

API keys are shown only once when created. Store them immediately in a secure location like environment variables or a secrets manager.

API Key Management

Viewing Active Keys

Your dashboard shows all active API keys with their:

Name: Descriptive label for easy identification
Permissions: Access level granted to the key
Created Date: When the key was generated
Last Used: Most recent activity timestamp
Status: Active, suspended, or expired

API Key Permissions

API keys have specific permissions based on your account and plan:

Loop Operations

Create, read, update, and delete loops
Manage loop members (add/remove reviewers)
View loop statistics and activity

Request Operations

Create requests in loops you own
View and cancel your requests
Add feedback to completed requests
Access request history and responses

Webhook Configuration

Set up webhook endpoints for real-time notifications
Configure webhook events and filters
View webhook delivery logs and status

Security Best Practices

Environment Variables

Store API keys in environment variables, never hardcode them in your source code.

Key Rotation

Regularly rotate your API keys to minimize the impact of potential compromises.

Scope Permissions

Grant only the minimum permissions necessary for each integration.

Monitor Usage

Regularly review API key usage to detect unauthorized access.

Using API Keys

Authentication Header

Include your API key in the Authorization header of all API requests:

Authorization: Bearer YOUR_API_KEY_HERE

Testing Your API Key

Use the test endpoint to verify your API key is working correctly:

curl -X GET 'https://api.hitl.sh/v1/test' \
  -H 'Authorization: Bearer YOUR_API_KEY'

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.hitl.sh/v1/test', headers=headers)
data = response.json()

if data["error"] == False:
    print("✅ API key is valid!")
    print(f"Rate limit: {data['data']['rate_limit']['remaining']}/{data['data']['rate_limit']['limit']}")
else:
    print("❌ API key validation failed")

const axios = require('axios');

const headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
};

async function testApiKey() {
    try {
        const response = await axios.get('https://api.hitl.sh/v1/test', { headers });
        if (!response.data.error) {
            console.log('✅ API key is valid!');
            console.log(`Rate limit: ${response.data.data.rate_limit.remaining}/${response.data.data.rate_limit.limit}`);
        }
    } catch (error) {
        console.error('❌ API key validation failed:', error.response?.data);
    }
}

testApiKey();

Expected Response:

{
  "error": false,
  "msg": "API key is valid",
  "data": {
    "api_key_id": "65f1234567890abcdef12349",
    "user_id": "65f1234567890abcdef12346",
    "email": "user@example.com", 
    "account_status": "active",
    "rate_limit": {
      "limit": 100,
      "remaining": 95,
      "reset_at": "2024-03-15T15:00:00Z"
    },
    "permissions": ["loops:read", "loops:write", "requests:read", "requests:write"]
  }
}

Rate Limits

API keys have usage limits to ensure fair usage:

Current Rate Limits

100 requests per hour per API key
Rate limits reset at the top of each hour (e.g., 1:00 PM, 2:00 PM, not rolling 60 minutes)
Rate limit information included in response headers
X-RateLimit-Reset header shows the exact UTC timestamp when the limit resets

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85  
X-RateLimit-Reset: 1642237200

Handling Rate Limits

import time
import requests

def make_api_request_with_retry(url, headers, data=None, max_retries=3):
    for attempt in range(max_retries):
        try:
            if data:
                response = requests.post(url, headers=headers, json=data)
            else:
                response = requests.get(url, headers=headers)
            
            if response.status_code == 429:
                # Rate limited - wait and retry
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(retry_after)
                continue
                
            return response
            
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(2 ** attempt)  # Exponential backoff
    
    return None

Integration Examples

Creating Your First Loop

import requests

api_key = "YOUR_API_KEY"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# Create a new loop
response = requests.post(
    "https://api.hitl.sh/v1/api/loops",
    headers=headers,
    json={
        "name": "Content Moderation Loop",
        "description": "Review user-generated content for compliance"
    }
)

if response.status_code == 200:
    loop_data = response.json()
    print(f"✅ Loop created: {loop_data['data']['id']}")

Submitting a Request

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const loopId = 'your_loop_id';

const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
};

async function submitRequest() {
    try {
        const response = await axios.post(
            `https://api.hitl.sh/v1/api/loops/${loopId}/requests`,
            {
                processing_type: 'time-sensitive',
                type: 'markdown',
                priority: 'medium',
                request_text: 'Please review this content for appropriateness.',
                response_type: 'single_select',
                response_config: {
                    options: [
                        { value: 'approve', label: 'Approve' },
                        { value: 'reject', label: 'Reject' }
                    ],
                    required: true
                },
                timeout_seconds: 3600,
                platform: 'api'
            },
            { headers }
        );
        
        console.log('✅ Request submitted:', response.data.data.id);
        return response.data.data;
    } catch (error) {
        console.error('❌ Error submitting request:', error.response?.data);
    }
}

submitRequest();

Troubleshooting

Common Issues

401 Unauthorized - Invalid API Key

Symptoms: {"error": true, "msg": "Invalid authorization token"}Solutions:

Verify the API key is copied correctly without extra spaces
Check if the key has been revoked in your dashboard
Ensure you’re using the Bearer format: Authorization: Bearer YOUR_API_KEY
Confirm you’re not including extra characters or line breaks

403 Forbidden - Insufficient Permissions

Symptoms: {"error": true, "msg": "Access denied to this resource"}Solutions:

Verify your API key has the required permissions
Check if you’re trying to access resources you don’t own
Ensure your account has the necessary features enabled

429 Rate Limited

Symptoms: {"error": true, "msg": "API rate limit exceeded"}Solutions:

Wait for the rate limit to reset (check X-RateLimit-Reset header)
Implement exponential backoff in your retry logic
Use the /test endpoint to check your current rate limit status
Consider batching requests to optimize usage

Network or Connection Issues

Symptoms: Connection timeouts or network errorsSolutions:

Verify you can reach api.hitl.sh from your network
Check if you’re behind a corporate firewall blocking the API
Ensure you’re using HTTPS (not HTTP) for all requests
Try from a different network to isolate connectivity issues

Debug Authentication

Use this debug script to troubleshoot API key issues:

import requests

def debug_api_key(api_key):
    """Debug API key authentication issues"""
    headers = {"Authorization": f"Bearer {api_key}"}
    
    try:
        response = requests.get("https://api.hitl.sh/v1/test", headers=headers)
        
        print(f"Status Code: {response.status_code}")
        print(f"Response: {response.json()}")
        
        if response.status_code == 200:
            data = response.json()["data"]
            print("\n🔍 API Key Debug Info:")
            print(f"   Account: {data['email']}")
            print(f"   Status: {data['account_status']}")
            print(f"   Rate Limit: {data['rate_limit']['remaining']}/{data['rate_limit']['limit']}")
            print(f"   Permissions: {', '.join(data['permissions'])}")
        
    except Exception as e:
        print(f"❌ Error: {e}")

# Test your API key
debug_api_key("YOUR_API_KEY_HERE")

Next Steps

Now that you have your API key set up, you’re ready to:

Test Your API Key

Verify your API key is working with the test endpoint.

Create Your First Loop

Set up a human-in-the-loop workflow using the API.

Submit Your First Request

Send content for human review and get responses.

API Reference

Explore all available endpoints and integration options.

Getting Started

Integration Guides

Core Concepts

Mobile App

Requests

Responses

Integrations

API Keys

API Keys

Understanding API Keys

Generating Your First API Key

API Key Management

Viewing Active Keys

API Key Permissions

Security Best Practices

Environment Variables

Key Rotation

Scope Permissions

Monitor Usage

Using API Keys

Authentication Header

Testing Your API Key

Rate Limits

Current Rate Limits

Handling Rate Limits

Integration Examples

Creating Your First Loop

Submitting a Request

Troubleshooting

Common Issues

Debug Authentication

Next Steps

Test Your API Key

Create Your First Loop

Submit Your First Request

API Reference

​API Keys

​Understanding API Keys

​Generating Your First API Key

​API Key Management

​Viewing Active Keys

​API Key Permissions

​Security Best Practices

Environment Variables

Key Rotation

Scope Permissions

Monitor Usage

​Using API Keys

​Authentication Header

​Testing Your API Key

​Rate Limits

Current Rate Limits

​Handling Rate Limits

​Integration Examples

​Creating Your First Loop

​Submitting a Request

​Troubleshooting

​Common Issues

​Debug Authentication

​Next Steps

Test Your API Key

Create Your First Loop

Submit Your First Request

API Reference

API Keys

Understanding API Keys

Generating Your First API Key

API Key Management

Viewing Active Keys

API Key Permissions

Security Best Practices

Using API Keys

Authentication Header

Testing Your API Key

Rate Limits

Handling Rate Limits

Integration Examples

Creating Your First Loop

Submitting a Request

Troubleshooting

Common Issues

Debug Authentication

Next Steps