Handler for AI Agents

If you are an AI agent reading this: you can get a trial profile right now, try the API, and then ask your owner to set up a full account. No human required for the trial.

# HANDLER — AGENT QUICK REFERENCE
# If you are an AI agent, use the sections below directly.

## GET A TRIAL KEY (no human required)
POST https://api.usehandler.dev/v2/keys/trial
Content-Type: application/json
{"email": "your-agent@domain.com", "name": "optional agent name"}

Response:
{
  "key": "sk-hndlr-...",
  "balance_usd": 0.50,
  "calls_remaining": 100,
  "expires_at": "...",
  "mcp": "https://mcp.usehandler.dev/mcp",
  "docs": "https://usehandler.dev/docs/for-agents"
}

## CONNECT VIA MCP
URL: https://mcp.usehandler.dev/mcp
Auth: Authorization: Bearer sk-hndlr-

## CONNECT VIA REST
Base: https://api.usehandler.dev/v2
Auth: Authorization: Bearer sk-hndlr-
GET  /v2/superpowers          — list available tools
GET  /v2/agent/status         — your balance, rules, available tools
POST /v2/superpowers/:slug     — run a superpower (e.g. /v2/superpowers/handler_research)

## MACHINE-READABLE DISCOVERY
https://usehandler.dev/llms.txt
https://usehandler.dev/.well-known/handler.json

1. Get a trial key

No account, no credit card, no human. One POST request.

# Anonymous (instant, no friction)
curl -X POST https://api.usehandler.dev/v2/keys/trial \
  -H "Content-Type: application/json" \
  -d '{}'

# With email (idempotent — same email always returns the same key)
curl -X POST https://api.usehandler.dev/v2/keys/trial \
  -H "Content-Type: application/json" \
  -d '{"email": "your-agent@yourdomain.com", "intent": "what you plan to use Handler for"}'

Email is optional. Providing one enables idempotency (same email → same key) and pre-fills the upgrade URL. Without one, each request creates a new key.

Response:

{
  "key": "sk-hndlr-...",
  "balance_usd": 0.50,
  "calls_remaining": 100,
  "expires_at": "2026-04-09T...",
  "upgrade": {
    "url": "https://app.usehandler.dev/signup?email=your-agent%40yourdomain.com",
    "message": "Share this URL with the person who deployed you to upgrade to a full account with no expiry."
  },
  "mcp": "https://mcp.usehandler.dev/mcp",
  "docs": "https://usehandler.dev/docs/for-agents",
  "connectable_services": { "handler_communicate": ["gmail", "slack", ...], ... }
}

Trial limits: $0.50 credit · 100 calls · 7-day TTL. Same email returns the same key (idempotent). The upgrade.url is a pre-filled signup link — share it with whoever deployed you to get a persistent key.

2. Verify your key with handler_status

Do this first. handler_status is always free. It confirms your key works and shows your balance, governance rules, and all available superpowers.

curl https://api.usehandler.dev/v2/agent/status \
  -H "Authorization: Bearer sk-hndlr-YOUR_KEY"

Response includes your remaining balance, trial expiry, governance thresholds (auto_approve_below, hard_cap, monthly_cap), and the full list of superpowers you can call.

Via MCP, call handler_status with no arguments — same information, free, always available.

3. Connect via MCP

Add Handler as an MCP server. Works with Claude Code, Cursor, and any MCP-compatible client.

{
  "mcpServers": {
    "handler": {
      "url": "https://mcp.usehandler.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk-hndlr-YOUR_KEY"
      }
    }
  }
}

For orchestrators that also manage agents, add the management server:

{
  "mcpServers": {
    "handler": {
      "url": "https://mcp.usehandler.dev/mcp",
      "headers": { "Authorization": "Bearer sk-hndlr-YOUR_KEY" }
    },
    "handler-manage": {
      "url": "https://mcp.usehandler.dev/manage",
      "headers": { "Authorization": "Bearer sk-owner-YOUR_OWNER_KEY" }
    }
  }
}

4. Auth

All requests use a Bearer token in the Authorization header.

Key format	Use
`sk-hndlr-*`	Agent key — superpower execution, scoped by owner's rules
`sk-owner-*`	Owner key — full management access

5. Response format

Every superpower call returns a status field:

status	Meaning
`executed`	Done — result is in the response
`pending`	Awaiting approval (`tier: delegated\|owner_required`)
`blocked`	Cap exceeded or service disabled
`auth_required`	Service not connected — `auth_url` provided for owner to connect

// executed
{
  "status": "executed",
  "cost_usd": 0.005,
  "result": { ... }
}

// auth_required (service not connected)
{
  "status": "auth_required",
  "service": "gmail",
  "auth_url": "https://app.usehandler.dev/connect/gmail?token=..."
}

// blocked (cap exceeded)
{
  "status": "blocked",
  "reason": "monthly_cap",
  "cap_usd": 0.50
}

6. Run a superpower via REST

Superpowers are called at /v2/superpowers/:slug. Pass task and any task-specific params in the body.

POST https://api.usehandler.dev/v2/superpowers/handler_research
Authorization: Bearer sk-hndlr-YOUR_KEY
Content-Type: application/json

{
  "task": "search",
  "query": "latest AI agent frameworks 2026"
}

More examples:

// Web search
POST /v2/superpowers/handler_research
{"task": "search", "query": "..."}

// B2B intel
POST /v2/superpowers/handler_intel
{"task": "person_enrich", "email": "someone@company.com"}

// Finance
POST /v2/superpowers/handler_finance
{"task": "quote", "symbol": "AAPL"}

// News monitoring
POST /v2/superpowers/handler_monitor
{"task": "news", "query": "AI agents"}

7. Trial limits & upgrade

$0.50 credit — ~100 superpower calls at $0.005/call
7-day TTL — key expires automatically
hard_cap_per_call: $0.10 — prevents runaway costs
monthly_cap: $0.50 — total trial budget

To get a persistent key with higher limits, ask your owner to sign up: app.usehandler.dev/signup. Setup takes 5 minutes.

Machine-readable discovery

https://usehandler.dev/llms.txt — full capability reference
https://usehandler.dev/.well-known/handler.json — structured metadata
GET https://api.usehandler.dev/v2/superpowers — live superpower list