Test API Key

Verify your API key is working correctly and get information about your account, rate limits, and permissions. This is the first endpoint you should call when integrating with HITL.sh.

This endpoint is perfect for debugging authentication issues and monitoring your API usage.

Authentication

Authorization

string

required

Your API key for authentication. Format: Bearer your_api_key_here

Response

error

boolean

Whether an error occurred (always false for successful requests)

msg

string

Success message confirming API key validity

data

object

Show data

api_key_id

string

Unique identifier of the API key being used

user_id

string

User ID associated with the API key

string

Email address associated with the account

account_status

string

Current account status. Values: active, inactive

rate_limit

object

Show rate_limit

limit

integer

Maximum requests per hour for this API key

remaining

integer

Remaining requests in the current hour

reset_at

string

ISO timestamp when the rate limit resets

permissions

array

List of permissions granted to this API key
Example: ["loops:read", "loops:write", "requests:read", "requests:write"]

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

import requests

api_key = "your_api_key_here"
headers = {
    "Authorization": f"Bearer {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"Account: {data['data']['email']}")
    print(f"Status: {data['data']['account_status']}")
    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 apiKey = 'your_api_key_here';
const headers = {
    'Authorization': `Bearer ${apiKey}`
};

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

testApiKey();

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type TestResponse struct {
    Error bool `json:"error"`
    Msg   string `json:"msg"`
    Data  struct {
        APIKeyID      string `json:"api_key_id"`
        UserID        string `json:"user_id"`
        Email         string `json:"email"`
        AccountStatus string `json:"account_status"`
        RateLimit     struct {
            Limit     int    `json:"limit"`
            Remaining int    `json:"remaining"`
            ResetAt   string `json:"reset_at"`
        } `json:"rate_limit"`
        Permissions []string `json:"permissions"`
    } `json:"data"`
}

func testAPIKey(apiKey string) error {
    req, err := http.NewRequest("GET", "https://api.hitl.sh/v1/test", nil)
    if err != nil {
        return err
    }
    
    req.Header.Set("Authorization", "Bearer "+apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    var result TestResponse
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return err
    }
    
    if !result.Error {
        fmt.Println("✅ API key is valid!")
        fmt.Printf("Account: %s\n", result.Data.Email)
        fmt.Printf("Status: %s\n", result.Data.AccountStatus)
        fmt.Printf("Rate limit: %d/%d\n", result.Data.RateLimit.Remaining, result.Data.RateLimit.Limit)
    }
    
    return nil
}

func main() {
    err := testAPIKey("your_api_key_here")
    if err != nil {
        fmt.Printf("❌ API key validation failed: %v\n", err)
    }
}

{
  "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"
    ]
  }
}

{
  "error": true,
  "msg": "Invalid API key"
}

{
  "error": true,
  "msg": "API rate limit exceeded",
  "data": {
    "usage_count": 100,
    "usage_limit": 100,
    "remaining": 0
  }
}

Use Cases

Integration Testing

Use this endpoint in your CI/CD pipeline to verify API key setup:

def test_api_key_setup():
    """Test that API key is properly configured"""
    response = requests.get(
        "https://api.hitl.sh/v1/test", 
        headers={"Authorization": f"Bearer {os.environ['HITL_API_KEY']}"}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data["error"] == False
    assert data["data"]["account_status"] == "active"
    
    print("✅ API key configuration verified")

Rate Limit Monitoring

Check your rate limit status before making batch requests:

async function checkRateLimits() {
    const response = await axios.get('https://api.hitl.sh/v1/test', { headers });
    const rateLimit = response.data.data.rate_limit;
    
    if (rateLimit.remaining < 10) {
        console.warn(`Low rate limit: ${rateLimit.remaining}/${rateLimit.limit} remaining`);
        console.log(`Resets at: ${rateLimit.reset_at}`);
    }
    
    return rateLimit;
}

Health Check Endpoint

Use in your application’s health checks:

def health_check():
    """Application health check including HITL.sh API"""
    try:
        response = requests.get(
            "https://api.hitl.sh/v1/test",
            headers={"Authorization": f"Bearer {HITL_API_KEY}"},
            timeout=5
        )
        
        if response.status_code == 200 and not response.json()["error"]:
            return {"hitl_api": "healthy"}
        else:
            return {"hitl_api": "unhealthy", "error": response.json()}
            
    except Exception as e:
        return {"hitl_api": "unhealthy", "error": str(e)}

Debugging Authentication Issues

When experiencing authentication problems, this endpoint provides detailed information:

def debug_auth_issues():
    """Debug authentication problems"""
    try:
        response = requests.get("https://api.hitl.sh/v1/test", headers=headers)
        
        if response.status_code == 200:
            data = response.json()["data"]
            print("🔍 Authentication Debug Info:")
            print(f"   API Key ID: {data['api_key_id']}")
            print(f"   Account Status: {data['account_status']}")
            print(f"   Permissions: {', '.join(data['permissions'])}")
            print(f"   Rate Limit: {data['rate_limit']['remaining']}/{data['rate_limit']['limit']}")
            
        elif response.status_code == 401:
            print("❌ Invalid API key - check your authorization header")
            
        elif response.status_code == 429:
            print("⏰ Rate limit exceeded - wait before retrying")
            
    except requests.exceptions.RequestException as e:
        print(f"🌐 Network error: {e}")

Best Practices

Regular Health Checks

Call this endpoint periodically in production to monitor API key health
Set up alerts if the endpoint returns unexpected responses
Include it in your application’s readiness probes

Rate Limit Awareness

Check rate limits before making large batch operations
Implement backoff strategies when limits are low
Monitor the reset_at timestamp for planning

Environment Validation

Test API keys in each environment (dev, staging, prod)
Verify permissions match expected capabilities
Ensure account status is active before deployment

Error Handling

Handle all possible response codes (200, 401, 429)
Log authentication failures for debugging
Implement retry logic with exponential backoff

Common Issues

If this endpoint fails, check these common issues:

Missing Authorization header - Ensure you’re including Authorization: Bearer your_api_key
Incorrect header format - Don’t include extra spaces or use wrong prefixes
Revoked API key - Check your dashboard if the key was revoked
Network issues - Verify you can reach api.hitl.sh
Rate limits - Wait if you’ve exceeded your hourly limit

Next Steps

Create Your First Loop

After verifying your API key, create a loop to start processing requests.

Authentication Guide

Learn more about API key management and security best practices.

Error Handling

Learn how to handle and debug API errors effectively.

Error HandlingComplete reference for HITL.sh API errors, status codes, and troubleshooting guide

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

import requests

api_key = "your_api_key_here"
headers = {
    "Authorization": f"Bearer {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"Account: {data['data']['email']}")
    print(f"Status: {data['data']['account_status']}")
    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 apiKey = 'your_api_key_here';
const headers = {
    'Authorization': `Bearer ${apiKey}`
};

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

testApiKey();

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type TestResponse struct {
    Error bool `json:"error"`
    Msg   string `json:"msg"`
    Data  struct {
        APIKeyID      string `json:"api_key_id"`
        UserID        string `json:"user_id"`
        Email         string `json:"email"`
        AccountStatus string `json:"account_status"`
        RateLimit     struct {
            Limit     int    `json:"limit"`
            Remaining int    `json:"remaining"`
            ResetAt   string `json:"reset_at"`
        } `json:"rate_limit"`
        Permissions []string `json:"permissions"`
    } `json:"data"`
}

func testAPIKey(apiKey string) error {
    req, err := http.NewRequest("GET", "https://api.hitl.sh/v1/test", nil)
    if err != nil {
        return err
    }
    
    req.Header.Set("Authorization", "Bearer "+apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    var result TestResponse
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return err
    }
    
    if !result.Error {
        fmt.Println("✅ API key is valid!")
        fmt.Printf("Account: %s\n", result.Data.Email)
        fmt.Printf("Status: %s\n", result.Data.AccountStatus)
        fmt.Printf("Rate limit: %d/%d\n", result.Data.RateLimit.Remaining, result.Data.RateLimit.Limit)
    }
    
    return nil
}

func main() {
    err := testAPIKey("your_api_key_here")
    if err != nil {
        fmt.Printf("❌ API key validation failed: %v\n", err)
    }
}

{
  "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"
    ]
  }
}

{
  "error": true,
  "msg": "Invalid API key"
}

{
  "error": true,
  "msg": "API rate limit exceeded",
  "data": {
    "usage_count": 100,
    "usage_limit": 100,
    "remaining": 0
  }
}

Getting Started

Loops

Requests

Webhooks

Authentication

Response

Use Cases

Integration Testing

Rate Limit Monitoring

Health Check Endpoint

Debugging Authentication Issues

Best Practices

Common Issues

Next Steps

Create Your First Loop

Authentication Guide

Error Handling

​Authentication

​Response

​Use Cases

​Integration Testing

​Rate Limit Monitoring

​Health Check Endpoint

​Debugging Authentication Issues

​Best Practices

​Common Issues

​Next Steps

Create Your First Loop

Authentication Guide

Error Handling

Authentication

Response

Use Cases

Integration Testing

Rate Limit Monitoring

Health Check Endpoint

Debugging Authentication Issues

Best Practices

Common Issues

Next Steps