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

# Quickstart

> Get up and running with Humancheck in 5 minutes

## Installation

Install Humancheck using pip:

```bash theme={null}
pip install humancheck
```

Or install from source:

```bash theme={null}
git clone https://github.com/shashisp/humancheck.git
cd humancheck
poetry install
```

## Step 1: Initialize Configuration

Create a configuration file:

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

```bash theme={null}
humancheck start
```

This launches:

* **API Server**: [https://api.humancheck.dev](https://api.humancheck.dev)
* **Dashboard**: [http://localhost:8501](http://localhost:8501)

<Tip>
  You can also start them separately:

  * `humancheck start --api-only` - Start only the API
  * `humancheck start --dashboard-only` - Start only the dashboard
</Tip>

## Step 3: Create Your First Review

### Using Python

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

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

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

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

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

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

```python theme={null}
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`):

```json theme={null}
{
  "mcpServers": {
    "humancheck": {
      "command": "humancheck",
      "args": ["mcp"]
    }
  }
}
```

2. Restart Claude Desktop

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

<CardGroup cols={2}>
  <Card title="Payment Approval" href="/use-cases/payment-approval">
    Review high-value payments before processing
  </Card>

  <Card title="Data Deletion" href="/use-cases/data-deletion">
    Ensure GDPR compliance with human review
  </Card>

  <Card title="Content Moderation" href="/use-cases/content-moderation">
    Human oversight for borderline content
  </Card>

  <Card title="SQL Execution" href="/use-cases/sql-execution">
    Review database operations before execution
  </Card>
</CardGroup>

## Troubleshooting

### Port Already in Use

```bash theme={null}
# Use different ports
humancheck start --port 8001
```

Or edit `humancheck.yaml`:

```yaml theme={null}
api_port: 8001
streamlit_port: 8502
```

### Database Issues

```bash theme={null}
# 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:
   ```bash theme={null}
   ps aux | grep streamlit
   ```

2. Check logs:
   ```bash theme={null}
   humancheck logs
   ```

3. Try accessing directly:
   ```bash theme={null}
   streamlit run frontend/streamlit_app.py
   ```

## CLI Commands Reference

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

* Full documentation: Check the [API Reference](/api-reference/introduction)
* Examples: See the `examples/` directory in the repository
* Issues: [GitHub Issues](https://github.com/shashisp/humancheck/issues)
* Discord: [Join our community](https://discord.gg/humancheck)

***

Happy reviewing! 🎉