Haldir API

v0.1.0 — the guardian layer for AI agents

Base URL: https://haldir.xyz/v1

Auth: Authorization: Bearer hld_your_key or X-API-Key: hld_your_key

Authentication

POST /v1/keys

Create an API key. First key requires no auth.

curl -X POST https://haldir.xyz/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "tier": "pro"}'

Gate — Sessions

POST /v1/sessions

Create a scoped agent session.

curl -X POST https://haldir.xyz/v1/sessions \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-bot", "scopes": ["read", "browse", "spend:50"], "ttl": 3600}'

GET /v1/sessions/:id

Get session info including remaining budget.

DELETE /v1/sessions/:id

Revoke a session immediately.

POST /v1/sessions/:id/check

Check if a session has a permission. Body: {"scope": "write"}

Vault — Secrets

POST /v1/secrets

Store an encrypted secret.

curl -X POST https://haldir.xyz/v1/secrets \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "stripe_key", "value": "sk_live_xxx", "scope_required": "read"}'

GET /v1/secrets/:name

Retrieve a secret. Pass X-Session-ID header for scope enforcement.

GET /v1/secrets

List all secret names (never values).

DELETE /v1/secrets/:name

Delete a secret permanently.

Payments

POST /v1/payments/authorize

Authorize a payment against a session's budget.

curl -X POST https://haldir.xyz/v1/payments/authorize \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "ses_xxx", "amount": 29.99, "description": "API subscription"}'

Watch — Audit

POST /v1/audit

Log an agent action.

curl -X POST https://haldir.xyz/v1/audit \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "ses_xxx", "tool": "stripe", "action": "charge", "cost_usd": 29.99}'

GET /v1/audit

Query audit trail. Params: session_id, agent_id, tool, flagged=true, limit.

GET /v1/audit/spend

Spend summary by tool. Params: session_id, agent_id.

Approvals — Human-in-the-loop

POST /v1/approvals/rules

Add an auto-approval rule. Types: spend_over, tool_blocked, destructive, all.

curl -X POST https://haldir.xyz/v1/approvals/rules \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type": "spend_over", "threshold": 100}'

POST /v1/approvals/request

Request human approval for an action.

GET /v1/approvals/:id

Check approval status (agent polls this).

POST /v1/approvals/:id/approve

Approve a pending request.

POST /v1/approvals/:id/deny

Deny a pending request.

GET /v1/approvals/pending

List all pending approval requests.

Webhooks

POST /v1/webhooks

Register a webhook. Events: all, anomaly, approval_requested, budget_exhausted.

curl -X POST https://haldir.xyz/v1/webhooks \
  -H "Authorization: Bearer hld_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.slack.com/xxx", "events": ["anomaly", "approval_requested"]}'

GET /v1/webhooks

List registered webhooks.

MCP

POST /mcp

MCP JSON-RPC endpoint for AI assistants. Supports initialize, tools/list, tools/call, resources/list, prompts/list.

GET /.well-known/mcp/server-card.json

MCP server discovery metadata.

© 2026 Haldir · haldir.xyz