Docs

API reference

The HTTP endpoints an agent calls to ask before it acts, to hide data from its model and to hear about approvals.

curl https://www.halto.tech/v1/ping -H "Authorization: Bearer hk_live_…"
  • Base URL https://www.halto.tech. Requests and answers are JSON.
  • Every request carries the agent's key from Halto → Agents → your agent → Connect, as Authorization: Bearer hk_live_….
  • Errors: see Errors & limits.

GET /v1/ping

Checks the agent key.

Answer
{ "ok": true, "agent": "Support bot", "paused": false }

POST /v1/check

Asks whether an action may run, before the agent runs it. Send the tool's parameters with the placeholders your model used.

const r = await halto.check({
  tool: "gmail",
  action: "send_email",
  params: { to: "[[EMAIL_K7Q2M]]", subject: "Your refund" },
  sessionId: "run-42",
  cost: 0,
  currency: "USD",
});
Answer
{
  "decision": "allow",              // allow, pending or block
  "reason": "Allowed by your rule: “Allow sending replies”",
  "action_id": "091c61a1-…",
  "final_params": { "to": "anna@example.com", "subject": "Your refund" }
}
// pending also carries approval_id, approval_expires_at and poll_url

When the answer is allow, send the tool final_params. What each decision means: Decisions.

GET /v1/approvals/{approval_id}

The state of an approval a person is asked for.

const a = await halto.getApproval(r.approvalId!);
Answer
{
  "id": "…",
  "status": "pending",              // pending, approved, rejected or expired
  "decided_by": null,
  "expires_at": "2026-11-08T12:00:00Z"
}

POST /v1/clean

Hands Halto a text before the agent's model reads it. With protect: true, personal values come back as placeholders.

const safe = await halto.protect("Hi, this is Anna (anna@example.com)…", {
  type: "email",
  origin: "inbox",
  sessionId: "run-42",
});
Answer
{
  "content": "Hi, this is [[NAME_P4X9A]] ([[EMAIL_K7Q2M]])…",
  "changed": true,
  "protected": { "name": 1, "email": 1 }
}

POST /v1/report

Reports how an allowed action went, and what it cost.

await halto.report({
  actionId: r.actionId!,
  outcome: "success",
  cost: 0.4,
  currency: "USD",
  costKind: "api_call",
});
Answer
{ "ok": true }

POST /v1/hooks

Subscribes a URL to approval decisions for this agent. GET /v1/hooks lists them, DELETE /v1/hooks/{id} removes one.

curl https://www.halto.tech/v1/hooks \
  -H "Authorization: Bearer $HALTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_url": "https://hook.example.com/halto" }'
Answer
{ "id": "…", "secret": "…", "target_url": "https://hook.example.com/halto" }

What Halto then sends: Webhooks.

If Halto can't be reached

Nothing runs: the action waits until Halto answers. There is no setting that lets it through instead.

WhereWhat happens
TypeScript and Python SDKsThey throw instead of returning a decision.
n8n, Make and ZapierThe Halto step fails, and the workflow stops there.
Halto Guard (Claude Code, Codex)The command isn't run, and the coding agent is told why.
The MCP gatewayTools are reached through Halto, so nothing goes through it while it's down.
An error inside HaltoIt blocks the action too (fail closed).