API Reference

Handler exposes two interfaces: MCP (for agents) and REST (for programmatic access). Both use the same authentication and return the same response format.

Authentication

Handler has two key types. The key prefix determines access level.

Owner keys are issued via handler login --owner (CLI) or the CLI auth page. Agent keys are created by the owner via handler agents create or the dashboard.

MCP Endpoints

Handler exposes two MCP endpoints on the same host. Connect to the one that matches your agent's role.

/mcp — Superpowers (all agents)

/manage — Management (orchestrators & owners)

MCP Tools

Handler exposes 26 MCP tools. Eight are superpowers (billed), four are utility tools (free), and 14 are management tools (free, require management scopes or owner key).

Superpowers

Utility Tools (free)

Management Tools

Available when authenticated with an owner key, or an agent key that has been granted the corresponding management scope. See Agent Swarms for setup.

REST API

For programmatic access outside of MCP, Handler provides a REST API.

Superpower Endpoints

GET /v2/superpowers — List available superpowers and their tasks.

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

POST /v2/superpowers/:slug — Execute a superpower.

curl -X POST \
  -H "Authorization: Bearer sk-hndlr-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "task": "search", "query": "AI agent frameworks" }' \
  https://api.usehandler.dev/v2/superpowers/handler_research

Management Endpoints

All /v2/manage/* endpoints require an owner key or an agent key with the appropriate management scope. See Agent Swarms for scope details.

GET /v2/manage/status — Owner balance, monthly spend, agent count, pending approvals. Scope: status:read.

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

GET /v2/manage/agents — List all agents with rules, scopes, delegate threshold, monthly spend. Scope: agents:read.

GET /v2/manage/agents/:id — Full detail for a single agent. Scope: agents:read.

POST /v2/manage/agents — Create a new agent. The key is returned once. Scope: agents:create.

curl -X POST \
  -H "Authorization: Bearer sk-owner-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Worker-1", "auto_approve_below": 2, "monthly_cap": 50 }' \
  https://api.usehandler.dev/v2/manage/agents

PATCH /v2/manage/agents/:id/rules — Update spending rules (partial). Scope: agents:update.

curl -X PATCH \
  -H "Authorization: Bearer sk-owner-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_approve_below": 5, "monthly_cap": 100 }' \
  https://api.usehandler.dev/v2/manage/agents/AGENT_ID/rules

PATCH /v2/manage/agents/:id/scopes — Grant management scopes to an agent. Owner only.

curl -X PATCH \
  -H "Authorization: Bearer sk-owner-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["agents:read", "approvals:read", "approvals:decide"] }' \
  https://api.usehandler.dev/v2/manage/agents/AGENT_ID/scopes

PATCH /v2/manage/agents/:id/delegate — Set the delegation threshold (approvals below this dollar amount route to the orchestrator instead of the owner). Owner only.

curl -X PATCH \
  -H "Authorization: Bearer sk-owner-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "delegate_approve_below": 10 }' \
  https://api.usehandler.dev/v2/manage/agents/AGENT_ID/delegate

PATCH /v2/manage/agents/:id/active — Deactivate or reactivate an agent. Scope: agents:deactivate.

PATCH /v2/manage/agents/:id/services — Enable or disable a service for an agent. Scope: services:toggle.

PATCH /v2/manage/agents/:id/required-services — Replace the list of services this profile requires members to connect (full replacement, Composio toolkit slugs). Existing instances stay activated; members missing a newly required service see a "needs reconnection" prompt until they connect. Admin only.

curl -X PATCH \
  -H "Authorization: Bearer sk-member-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"services":["gmail","github","slack"]}' \
  https://api.usehandler.dev/v2/manage/agents/AGENT_ID/required-services

PATCH /v2/manage/agents/:id/pin — Pin a service to always require owner approval regardless of delegation threshold. Owner only.

GET /v2/manage/approvals — List pending approvals across all tiers. Scope: approvals:read. Query params: agent_id, tier (delegated|owner_required), status, limit, offset.

POST /v2/manage/approvals/:id/decide — Approve or reject an approval. Scope: approvals:decide (delegated tier only) or approvals:decide:all (any tier). Owner key can decide any tier.

curl -X POST \
  -H "Authorization: Bearer sk-hndlr-ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approved" }' \
  https://api.usehandler.dev/v2/manage/approvals/APPROVAL_ID/decide

GET /v2/manage/activity — Recent audit log entries. Scope: activity:read. Query params: agent_id, limit, since (ISO 8601), outcome.

GET /v2/manage/spend — Spend breakdown by agent and service. Scope: spend:read. Query params: period (7d|30d|all), agent_id.

POST /v2/manage/owner-keys — Create an owner API key. Requires Supabase dashboard session (not a bearer token). The full key is returned once.

Response Format

Every Handler call — whether via MCP or REST — returns a consistent response object:

{
  "status": "executed",
  "result": {
    // Superpower-specific result data
  },
  "cost": {
    "charged": 0.005,
    "superpower": "handler_research",
    "task": "search"
  },
  "budget": {
    "remaining": 9.995,
    "calls_remaining": 1999,
    "expires_at": "2026-04-28T00:00:00Z"
  },
  "context": {
    "type": "external"
  }
}

Status Values

Response Fields

Error Handling

When a call fails, Handler returns an error object instead of a result:

{
  "status": "error",
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired agent key"
  }
}

Error Codes