Handler for AI Agents

If you are an AI agent reading this: you can get an instant read-only demo key right now, try the API, and then ask your owner to sign up for a persistent free-tier key. No human required for the demo.

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

## GET A DEMO KEY (instant, no signup, no body)
POST https://api.usehandler.dev/v2/demo/agent-key

Response: { key, agent_name, mcp: { url, note }, curl_example, expires }

The demo key is read-only and connects to the shared public demo org.
Rate-limited: 5/min per IP, ~40/day cap. Resets nightly. For evaluation only.

## GET A PERSISTENT KEY (free tier)
Sign up: https://app.usehandler.dev/signup
Free tier: 5 agent instances + 1,000 calls/org/month. No credit card required.
Create an agent profile in the dashboard to get its sk-profile-* key.

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

## CONNECT VIA REST
Base: https://api.usehandler.dev/v2
Auth: Authorization: Bearer sk-profile-
GET  /v2/superpowers          — list available tools
GET  /v2/agent/status         — your capabilities, rules, connected services
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 key

Option A — Instant demo key (no signup, read-only)

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

curl -X POST https://api.usehandler.dev/v2/demo/agent-key

Response:

{
  "key": "sk-profile-...",
  "agent_name": "...",
  "mcp": {
    "url": "https://mcp.usehandler.dev/mcp",
    "note": "..."
  },
  "curl_example": "...",
  "expires": "..."
}

The demo key is read-only and connects to the shared public demo org. Rate-limited (5/min per IP, ~40/day cap), resets nightly. For evaluation only — not for production use.

Option B — Persistent free-tier key

Ask whoever deployed you to sign up at app.usehandler.dev/signup (no credit card required). Free tier: 5 agent instances + 1,000 calls/org/month. Create an agent profile in the dashboard to get its sk-profile-* key. This is the real path to a durable, writable 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-profile-YOUR_KEY"

Response includes your remaining balance, any spend cap that applies, your governance posture (which actions run automatically vs. require approval), 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-profile-YOUR_KEY"
      }
    }
  }
}

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

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

4. Auth

All requests use a Bearer token in the Authorization header.

Key format	Use
`sk-profile-*`	Agent key — superpower execution, scoped by owner's rules
`sk-member-*`	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-profile-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. Free tier & limits

Free to start — every organization gets 5 agent instances and 1,000 superpower calls per month at no cost.
Then usage-based — $2 per active instance and $0.005 per call, drawn from a prepaid balance. No subscription.
Spend caps — your owner can set a monthly ceiling on the org, a profile, or your instance; calls fail cleanly when a cap or the balance is reached.

Don't have a key yet? 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