API Reference

Overview

The FirstHelm API is a JSON API. All requests and responses use JSON. The base URL is https://firsthelm.dev/functions. Each endpoint is a function path under that base (for example, https://firsthelm.dev/functions/logActivity). Responses return standard HTTP status codes; errors use the schema documented below.

Authentication

Authenticate every request with an API key in the Authorization header. Keys are issued in Settings → API. Never expose a key in client-side code.

bash
curl https://firsthelm.dev/functions/registerAgent \
  -H "Authorization: Bearer hm_live_8f2c..."

Register an agent

bash
curl -X POST https://firsthelm.dev/functions/registerAgent \
  -H "Authorization: Bearer hm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Scout","framework":"langchain","endpoint_url":"https://my-runner/agents/scout"}'

json
{
  "status": "ok",
  "agent": {
    "id": "agt_01HX...",
    "name": "Scout",
    "framework": "langchain",
    "status": "idle",
    "autonomy_level": 0
  }
}

Log an activity

bash
curl -X POST https://firsthelm.dev/functions/logActivity \
  -H "Authorization: Bearer hm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agt_01HX...","action_type":"tool_call","description":"Called send_email API","risk_level":"high","cost_cents":12,"tokens_used":840}'

json
{
  "status": "ok",
  "activity": {
    "id": "act_01HX...",
    "action_type": "tool_call",
    "risk_level": "high"
  }
}

Request an approval

bash
curl -X POST https://firsthelm.dev/functions/requestApproval \
  -H "Authorization: Bearer hm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agt_01HX...","action":"deploy_to_prod","risk_level":"critical","timeout_minutes":30,"proposed_payload":{"service":"billing"}}'

json
{
  "status": "ok",
  "approval": {
    "id": "apr_01HX...",
    "status": "pending",
    "timeout_minutes": 30
  }
}

Decide an approval

bash
curl -X POST https://firsthelm.dev/functions/processApproval \
  -H "Authorization: Bearer hm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"approval_id":"apr_01HX...","decision":"approved","reason":"LGTM"}'

json
{
  "status": "ok",
  "approval": {
    "id": "apr_01HX...",
    "status": "approved",
    "decided_by": "operator@acme.com"
  }
}

Evaluate constraints

bash
curl -X POST https://firsthelm.dev/functions/evaluateConstraint \
  -H "Authorization: Bearer hm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agt_01HX...","action_type":"tool_call","action_description":"send_bulk_email","estimated_cost_cents":1200}'

json
{
  "result": "pass",
  "violations": 0,
  "constraints_evaluated": 4
}

In-app management

These operations are managed in the FirstHelm dashboard rather than over the API:

Webhooks

Subscribe to platform events. Configure endpoint URLs in Settings → Connections.

Errors

json
{
  "error": "Rate limit exceeded. Try again shortly."
}

For API questions, integration help, or to report an issue, email support@firsthelm.dev.