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.

The REST API is the most universal way to integrate Humancheck with any AI agent, regardless of framework or language. It provides a simple HTTP interface for creating reviews, checking status, and retrieving decisions.

​
Base URL

The base URL depends on which Humancheck product you’re using:

​
Platform (Cloud)

https://api.humancheck.dev

Using Platform?

Managed cloud service with production-scale infrastructure. Get started in minutes with no setup required.

​
Open Source (Self-Hosted)

http://localhost:8000  # Local development
https://your-domain.com  # Production deployment

Using Open Source?

Self-host the Humancheck stack for full control over data, deployment, and customization.

​
Authentication

​
Platform

All API requests require authentication using an API key. Include your API key in the Authorization header: 
headers = {
    "Authorization": "Bearer your-api-key-here",
    "Content-Type": "application/json"
}
Get your API key from platform.humancheck.dev under your organization settings.

​
Open Source

Authentication is optional. By default, the API is open. You can enable authentication in humancheck.yaml: 
enable_auth: true
api_key: your-secret-api-key
When enabled, include the API key in the Authorization header as shown above.

​
Creating a Review

​
Basic Review Request

import httpx

async with httpx.AsyncClient() as client:
    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": "Payment exceeds auto-approval limit",
            "confidence_score": 0.85,
            "urgency": "high",
            "blocking": False
        }
    )
    review = response.json()
    print(f"Review ID: {review['id']}")

​
Blocking Request

Wait for the decision before proceeding: 
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",
        "agent_reasoning": "High-value payment",
        "confidence_score": 0.85,
        "urgency": "high",
        "blocking": True  # Wait for decision
    }
)
review = response.json()

# Decision is included in the response
if review.get("decision"):
    decision = review["decision"]
    if decision["decision_type"] == "approve":
        process_payment()

​
Review Fields

FieldTypeRequiredDescription
task_typestringYesType of task (e.g., “payment”, “data_deletion”)
proposed_actionstringYesThe action to be reviewed
agent_reasoningstringNoWhy the agent is requesting review
confidence_scorefloatNoConfidence score (0.0-1.0)
urgencystringNoUrgency level: “low”, “medium”, “high”, “critical”
frameworkstringNoFramework identifier (e.g., “langchain”, “custom”)
metadataobjectNoCustom metadata object
organization_idintegerNoOrganization ID for multi-tenancy
agent_idintegerNoRegistered agent ID
blockingbooleanNoWait for decision (default: false)

​
Checking Review Status

​
Get Review Details

response = await client.get(
    f"https://api.humancheck.dev/reviews/{review_id}",
    headers={"Authorization": "Bearer your-api-key-here"}
)
review = response.json()

print(f"Status: {review['status']}")
print(f"Task Type: {review['task_type']}")
print(f"Proposed Action: {review['proposed_action']}")

​
List Reviews

# List all reviews
response = await client.get(
    "https://api.humancheck.dev/reviews",
    headers={"Authorization": "Bearer your-api-key-here"}
)
reviews = response.json()

# Filter by status
response = await client.get(
    "https://api.humancheck.dev/reviews",
    params={"status": "pending"}
)

# Filter by task type
response = await client.get(
    "https://api.humancheck.dev/reviews",
    params={"task_type": "payment"}
)

# Pagination
response = await client.get(
    "https://api.humancheck.dev/reviews",
    params={"page": 1, "page_size": 20}
)

​
Getting Decisions

​
Check for Decision

response = await client.get(
    f"https://api.humancheck.dev/reviews/{review_id}/decision",
    headers={"Authorization": "Bearer your-api-key-here"}
)
decision = response.json()

if decision:
    print(f"Decision: {decision['decision_type']}")
    if decision["decision_type"] == "approve":
        print("✅ Approved")
    elif decision["decision_type"] == "reject":
        print(f"❌ Rejected: {decision.get('notes')}")
    elif decision["decision_type"] == "modify":
        print(f"✏️ Modified: {decision['modified_action']}")
else:
    print("⏳ Still pending")

​
Polling for Decision

import asyncio

async def wait_for_decision(review_id, timeout=300, poll_interval=5):
    """Poll for decision with timeout."""
    async with httpx.AsyncClient() as client:
        start_time = asyncio.get_event_loop().time()
        
        while True:
            elapsed = asyncio.get_event_loop().time() - start_time
            if elapsed > timeout:
                raise TimeoutError("Decision timeout")
            
            response = await client.get(
                f"https://api.humancheck.dev/reviews/{review_id}/decision"
            )
            decision = response.json()
            
            if decision:
                return decision
            
            await asyncio.sleep(poll_interval)

# Usage
decision = await wait_for_decision(review_id, timeout=300)

​
Making Decisions (from Dashboard or API)

​
Approve a Review

response = await client.post(
    f"https://api.humancheck.dev/reviews/{review_id}/decide",
    json={
        "reviewer_id": 1,  # User ID
        "decision_type": "approve",
        "notes": "Payment approved"
    }
)

​
Reject a Review

response = await client.post(
    f"https://api.humancheck.dev/reviews/{review_id}/decide",
    json={
        "reviewer_id": 1,
        "decision_type": "reject",
        "notes": "Vendor not verified"
    }
)

​
Modify a Review

response = await client.post(
    f"https://api.humancheck.dev/reviews/{review_id}/decide",
    json={
        "reviewer_id": 1,
        "decision_type": "modify",
        "modified_action": "Process payment of $4,500 to ACME Corp",
        "notes": "Reduced amount per policy"
    }
)

​
Submitting Feedback

response = await client.post(
    f"https://api.humancheck.dev/reviews/{review_id}/feedback",
    headers={
        "Authorization": "Bearer your-api-key-here",
        "Content-Type": "application/json"
    },
    json={
        "rating": 5,  # 1-5 scale
        "comment": "Quick and clear decision, thank you!"
    }
)

​
Error Handling

try:
    response = await client.post(
        "https://api.humancheck.dev/reviews",
        json={...}
    )
    response.raise_for_status()
    review = response.json()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 400:
        print("Bad request:", e.response.json())
    elif e.response.status_code == 404:
        print("Review not found")
    elif e.response.status_code == 408:
        print("Request timed out waiting for decision")
    else:
        print(f"Error: {e.response.status_code}")

​
Complete Example

import httpx
import asyncio

async def payment_workflow(amount, vendor):
    """Example workflow for payment approval."""
    async with httpx.AsyncClient() as client:
        # Create review
        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": f"Process payment of ${amount} to {vendor}",
                "agent_reasoning": f"Payment amount (${amount}) exceeds auto-approval limit",
                "confidence_score": 0.85,
                "urgency": "high" if amount > 5000 else "medium",
                "blocking": True  # Wait for decision
            }
        )
        review = response.json()
        
        # Check if decision is ready
        if review.get("decision"):
            decision = review["decision"]
        else:
            # Poll for decision
            decision = await wait_for_decision(review["id"])
        
        # Process based on decision
        if decision["decision_type"] == "approve":
            process_payment(amount, vendor)
        elif decision["decision_type"] == "modify":
            # Extract amount from modified action
            modified_action = decision["modified_action"]
            process_payment_from_action(modified_action)
        else:
            print("Payment rejected")
            return None

asyncio.run(payment_workflow(5000, "ACME Corp"))

​
Using with cURL

​
Create Review

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",
    "agent_reasoning": "High-value payment",
    "confidence_score": 0.85,
    "urgency": "high"
  }'

​
Get Review

curl https://api.humancheck.dev/reviews/1 \
  -H "Authorization: Bearer your-api-key-here"

​
Get Decision

curl https://api.humancheck.dev/reviews/1/decision \
  -H "Authorization: Bearer your-api-key-here"

​
Next Steps