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.
{ "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",
});{
"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_urlWhen 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!);{
"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",
});{
"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",
});{ "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" }'{ "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.
| Where | What happens |
|---|---|
| TypeScript and Python SDKs | They throw instead of returning a decision. |
| n8n, Make and Zapier | The 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 gateway | Tools are reached through Halto, so nothing goes through it while it's down. |
| An error inside Halto | It blocks the action too (fail closed). |