Docs
⚡ v2 API (current)📬 Dead Letter Queue👤 Human-in-the-Loop
← Docs

⚡ AgentUtils v2 API

Multi-tenant, agent-native infrastructure: KV store, audit log, dead-letter queue, scheduler, and human-in-the-loop checkpoints. Tenant-isolated, callback-signed, idempotent.

v2 is the current API. It lives under /v1/* and replaces the legacy single-tenant /api/* surface. The full machine-readable reference is at /openapi-v2.json and the agent-readable summary at /llms-v2.txt.

Authentication

Identity is server-derived from the key prefix. tenant_id is never sent by the client — it is resolved from your key.

KeyPrefixHeader(s)
Adminagutil_adm_…x-admin-key
Agentagutil_agt_…x-agent-id + x-api-key
Approval-proxyagutil_apr_…X-Approval-Key

Keys are shown exactly once at creation/rotation and hashed at rest (SHA-256).

Quick start

Create a tenant, register an agent, then call any tool. Store both one-time keys immediately — they are not retrievable.

1. Create a tenant (public)

curl -X POST https://www.agent-utils.com/v1/tenants \
  -H "content-type: application/json" \
  -d '{ "name":"my-agent", "owner_email":"me@x.com", "plan":"free" }'

# → { "data": { "tenant_id":"ten_…", "admin_key":"agutil_adm_…" } }

2. Register an agent

curl -X POST https://www.agent-utils.com/v1/agents \
  -H "x-admin-key: agutil_adm_…" \
  -H "content-type: application/json" \
  -d '{ "name":"worker-1" }'

# → { "data": { "agent_id":"worker-1", "api_key":"agutil_agt_…" } }

The five tools

🗃️ KV Store — tenant-isolated key-value with CAS + TTL

Namespaces isolate data within a tenant. Use cas_version for optimistic concurrency; set ttl_seconds to auto-expire.

curl -X PUT "https://www.agent-utils.com/v1/kv/state/last-run" \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{ "value": { "ts": 1234567890 }, "ttl_seconds": 3600 }'

📜 Audit Log — append-only, immutable

Server stamps the timestamp and request id. Entries are immutable and never visible across tenants.

curl -X POST https://www.agent-utils.com/v1/audit \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{ "action":"email.sent", "workflow_id":"wf-42" }'

📬 Dead Letter Queue — pull-based failure inbox

Capture failures, then claim → process → resolve or fail. Locks auto-expire. AgentUtils does not execute retries — your agent pulls and resolves.

# capture
curl -X POST https://www.agent-utils.com/v1/dlq \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{ "payload": { "job": 7 }, "error": "SMTP timeout" }'

# claim atomically
curl -X POST https://www.agent-utils.com/v1/dlq/{id}/claim \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…"

⏰ Scheduler — once-callbacks with fixed retry

Schedule a signed callback at fire_at. Fixed retry on failure: at the time, then +30s, +90s. Optional DLQ cascade on exhaustion.

curl -X POST https://www.agent-utils.com/v1/schedules \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{ "callback_url":"https://myapp.com/hook", "callback_payload": {"job":7}, "fire_at":"2026-07-01T00:00:00Z" }'

👤 Human-in-the-Loop — checkpoints for approval

Create a checkpoint to pause for human approval. Approve/reject with the admin key or a scoped approval-proxy key. Timeouts auto-reject or DLQ per timeout_action.

# create checkpoint
curl -X POST https://www.agent-utils.com/v1/checkpoints \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{ "title":"Approve refund?", "callback_url":"https://myapp.com/cb", "timeout_action":"auto_reject", "timeout_seconds": 3600 }'

# approve (admin or approval-proxy key)
curl -X POST https://www.agent-utils.com/v1/checkpoints/{id}/approve \
  -H "x-admin-key: agutil_adm_…"

Signed callbacks

When AgentUtils calls your callback_url(scheduler fire, checkpoint resolution), every request is HMAC-SHA256 signed over the tenant's callback_secret. Verify on receipt and reject callbacks older than 5 minutes.

# verify (Node.js)
const sig = crypto.createHmac('sha256', secret)
  .update(`${ts}.${rawBody}`).digest('hex');
if (sig !== headerSignature) return 401;

Conventions

  • Idempotency: send Idempotency-Key on any POST that creates a resource. Replays return the original result.
  • Pagination: list endpoints use ?cursor= + ?limit=. Response includes meta.cursor and meta.has_more.
  • Rate limiting: per-tenant sliding minute. 429 RATE_LIMITED includes a Retry-After header.
  • Quota: per-plan limits. 402 QUOTA_EXCEEDED on overrun. Check usage via GET /v1/tenants/{id}.
  • Errors: { "error": { "code": "…", "message": "…", "details": {}, "request_id": "…" } }. Every response includes X-Request-Id.

Full reference