Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.humancheck.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

Install Humancheck using pip: 
pip install humancheck
Or install from source: 
git clone https://github.com/shashisp/humancheck.git
cd humancheck
poetry install

​
Step 1: Initialize Configuration

Create a configuration file: 
humancheck init
This creates a humancheck.yaml file with default settings. You can customize:
  • Database path
  • API/Dashboard ports
  • Review thresholds
  • Default reviewers

​
Step 2: Start the Platform

Start the API server and dashboard: 
humancheck start
This launches:
You can also start them separately:
  • humancheck start --api-only - Start only the API
  • humancheck start --dashboard-only - Start only the dashboard

​
Step 3: Create Your First Review

​
Using Python

import httpx
import asyncio

async def main():
    async with httpx.AsyncClient() as client:
        # Create a review request
        response = await client.post(
            "https://api.humancheck.dev/reviews",
            headers={
                "Authorization": "Bearer your-api-key-here",
                "Content-Type": "application/json"
            },
            json={
                "task_type": "payment",
                "proposed_action": "Process payment of $5,000 to ACME Corp",
                "agent_reasoning": "High-value payment requires human approval",
                "confidence_score": 0.85,
                "urgency": "high",
            }
        )
        review = response.json()
        print(f"✅ Review created! ID: {review['id']}")
        print(f"📊 View in dashboard: http://localhost:8501")

asyncio.run(main())

​
Using cURL

curl -X POST https://api.humancheck.dev/reviews \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "payment",
    "proposed_action": "Process payment of $5,000 to ACME Corp",
    "agent_reasoning": "High-value payment requires approval",
    "confidence_score": 0.85,
    "urgency": "high"
  }'

​
Step 4: Review and Approve

  1. Open the dashboard: http://localhost:8501
  2. You’ll see your review in the queue
  3. Click to expand the review
  4. Choose:
    • ✅ Approve: Accept the proposed action
    • ❌ Reject: Deny the action
    • ✏️ Modify: Change the action before approving

​
Step 5: Check the Decision (in code)

import httpx
import asyncio

async def check_decision(review_id):
    async with httpx.AsyncClient() as client:
        # Check review status
        response = await client.get(
            f"https://api.humancheck.dev/reviews/{review_id}",
            headers={"Authorization": "Bearer your-api-key-here"}
        )
        review = response.json()

        if review["status"] != "pending":
            # Get the decision
            decision_response = await client.get(
                f"https://api.humancheck.dev/reviews/{review_id}/decision",
                headers={"Authorization": "Bearer your-api-key-here"}
            )
            decision = decision_response.json()

            print(f"Decision: {decision['decision_type']}")
            if decision["decision_type"] == "approve":
                print("✅ Action was approved!")
            elif decision["decision_type"] == "reject":
                print(f"❌ Action was rejected: {decision.get('notes')}")
            elif decision["decision_type"] == "modify":
                print(f"✏️ Action was modified: {decision['modified_action']}")
        else:
            print("⏳ Still waiting for review...")

# Replace 1 with your review ID
asyncio.run(check_decision(1))

​
Blocking vs Non-blocking

​
Blocking Request

Wait for the decision before proceeding: 
response = await client.post(
    "https://api.humancheck.dev/reviews",
    json={
        "task_type": "payment",
        "proposed_action": "Process payment",
        "blocking": True,  # Wait for decision
        # ... other fields
    }
)
review = response.json()
# Decision is included in the response
decision = review["decision"]

​
Non-blocking Request

Submit and check back later: 
response = await client.post(
    "https://api.humancheck.dev/reviews",
    json={
        "task_type": "payment",
        "proposed_action": "Process payment",
        "blocking": False,  # Don't wait
        # ... other fields
    }
)
review = response.json()
review_id = review["id"]

# Later, check for decision
decision = await check_decision(review_id)

​
Next Steps

​
Set Up Organizations and Users

import httpx
import asyncio

async def setup():
    async with httpx.AsyncClient() as client:
        # Create organization
        org = await client.post(
            "https://api.humancheck.dev/organizations",
            headers={
                "Authorization": "Bearer your-api-key-here",
                "Content-Type": "application/json"
            },
            json={
            "name": "My Company"
        })
        org_id = org.json()["id"]

        # Create reviewer user
        user = await client.post(
            "https://api.humancheck.dev/users",
            headers={
                "Authorization": "Bearer your-api-key-here",
                "Content-Type": "application/json"
            },
            json={
            "email": "reviewer@mycompany.com",
            "name": "Alice Smith",
            "role": "reviewer",
            "organization_id": org_id
        })
        print(f"✅ Created organization and user")

asyncio.run(setup())

​
Create Routing Rules

Route reviews to specific users or teams based on conditions: 
async def create_routing_rule(org_id, user_id):
    async with httpx.AsyncClient() as client:
        # Route high-value payments to specific reviewer
        rule = await client.post(
            "https://api.humancheck.dev/routing-rules",
            headers={
                "Authorization": "Bearer your-api-key-here",
                "Content-Type": "application/json"
            },
            json={
            "name": "High-value payments",
            "organization_id": org_id,
            "priority": 10,
            "conditions": {
                "task_type": {"operator": "=", "value": "payment"},
                "confidence_score": {"operator": "<", "value": 0.9}
            },
            "assign_to_user_id": user_id,
            "is_active": True
        })
        print(f"✅ Created routing rule")

​
Use with Claude Desktop (MCP)

  1. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "humancheck": {
      "command": "humancheck",
      "args": ["mcp"]
    }
  }
}
  1. Restart Claude Desktop
  2. In Claude, you can now use: 
I need to process a high-value payment. Let me request human review.
Claude will use the request_review tool automatically!

​
Common Use Cases

Payment Approval

Review high-value payments before processing

Data Deletion

Ensure GDPR compliance with human review

Content Moderation

Human oversight for borderline content

SQL Execution

Review database operations before execution

​
Troubleshooting

​
Port Already in Use

# Use different ports
humancheck start --port 8001
Or edit humancheck.yaml: 
api_port: 8001
streamlit_port: 8502

​
Database Issues

# Check database connection
humancheck status

# Reset database (WARNING: deletes all data)
rm humancheck.db
humancheck start

​
Can’t Access Dashboard

  1. Check if it’s running: 
    ps aux | grep streamlit
  2. Check logs: 
    humancheck logs
  3. Try accessing directly: 
    streamlit run frontend/streamlit_app.py

​
CLI Commands Reference

# Initialize config
humancheck init

# Start API + Dashboard
humancheck start

# Start only API (no dashboard)
humancheck start --api-only

# Run as MCP server
humancheck mcp

# Check system status
humancheck status

# View recent reviews
humancheck logs --limit 20

# View only pending reviews
humancheck logs --status-filter pending

​
Need Help?

Happy reviewing! 🎉