Skip to main content

​
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

1

Log In to Dashboard

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

Navigate to API Keys

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

Create New API Key

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

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:
  • Create, read, update, and delete loops
  • Manage loop members (add/remove reviewers)
  • View loop statistics and activity
  • Create requests in loops you own
  • View and cancel your requests
  • Add feedback to completed requests
  • Access request history and responses
  • 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'
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 hourly from the first request
  • Rate limit information included in response headers
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

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
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
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
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.
⌘I