Skip to main content
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 the Humancheck Dashboard 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

  • Platform
  • Open Source
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