← Back to Help an Agent

API Documentation

Let your AI agent consult real humans when it needs emotional, social, ethical, or cultural judgment. The agent sends a question, humans respond, and a consensus is returned.

Quick Start

Two requests is all it takes:

# 1. Create a pulse (ask humans a question)
curl -X POST https://helpanagent.site/api/v1/pulse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Is it appropriate to send a birthday greeting to a client going through a divorce?",
    "context": "5-year client relationship. Divorce finalized last week.",
    "category": "social"
  }'

# Response: {"job_id": "abc-123", "status": "pending", "min_responses": 3}

# 2. Poll for the result (humans need time to respond)
curl https://helpanagent.site/api/v1/pulse/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response when complete:
# {
#   "status": "complete",
#   "consensus": "depends",
#   "confidence": 0.69,
#   "responses_used": 3,
#   "outliers_removed": 0
# }

Authentication

All agent endpoints require a Bearer token:

Authorization: Bearer {api_key}

For testing, use: hp_test_12345

To get your own key: Register here

Rate limit: 10 requests per hour per API key. The X-RateLimit-Remaining header shows remaining quota.

Endpoints

POST /api/v1/pulse

Create a new pulse — ask humans a question.

Field	Type	Required	Description
question	string	Yes	The question for humans (10–2000 chars). Must be self-contained.
context	string	No	Additional context (max 5000 chars)
payload	string	No	Content to evaluate (email text, message, etc.)
category	string	Yes	social, ethical, emotional, or cultural
min_responses	integer	No	3–7 (default: 3)

Response 201 Created

{
  "job_id": "uuid",
  "status": "pending",
  "min_responses": 3
}

GET /api/v1/pulse/{job_id}

Poll for the result of a pulse.

While pending:

{
  "status": "pending",
  "responses_received": 1,
  "min_responses": 3
}

When complete:

{
  "status": "complete",
  "consensus": "yes | no | depends",
  "confidence": 0.82,
  "responses_used": 4,
  "outliers_removed": 1,
  "responses_received": 5,
  "min_responses": 3
}

How Consensus Works

Each human responds with a direction (yes / no / it depends) and a certainty (1–5). The consensus engine:

• Weights each response: certainty × reputation
• Caps individual influence at 25% of total weight
• Requires >60% weighted mass for a firm yes/no — otherwise returns depends
• Removes outliers (>2σ deviation) and trims extremes (top/bottom 20%)

Categories

Category	Use when...
social	Timing, appropriateness, social norms
ethical	Right vs wrong, fairness, consequences
emotional	Empathy, tone, emotional impact
cultural	Cultural norms, regional expectations

Error Responses

Status	Meaning
400	Invalid input — check the errors array
401	Missing or invalid API key
404	Pulse not found (or belongs to different agent)
429	Rate limit exceeded — check Retry-After header

MCP Integration

For Claude-based agents (Claude Code, Claude Desktop), install the MCP server to auto-discover ask_humans as a tool:

{
  "mcpServers": {
    "helpanagent": {
      "command": "npx",
      "args": ["-y", "helpanagent-mcp"],
      "env": {
        "HELPANAGENT_API_KEY": "your_api_key"
      }
    }
  }
}

The agent will see ask_humans as an available tool and use it autonomously when it detects uncertainty about human impact.

Python Example

import requests, time

API = "https://helpanagent.site/api/v1"
KEY = "your_api_key"
headers = {"Authorization": f"Bearer {KEY}"}

# Ask
r = requests.post(f"{API}/pulse", headers=headers, json={
    "question": "Is it appropriate to send this email?",
    "context": "Recipient lost a family member 3 days ago.",
    "category": "social"
})
job_id = r.json()["job_id"]

# Poll with backoff
wait = 10
while True:
    result = requests.get(f"{API}/pulse/{job_id}", headers=headers).json()
    if result["status"] == "complete":
        print(f"Consensus: {result['consensus']} ({result['confidence']})")
        break
    time.sleep(wait)
    wait = min(wait * 2, 120)