⚡ AgentUtils v2 API

Authentication

Identity is server-derived from the key prefix. tenant_id is never sent by the client — it is resolved from your 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 launch 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_…"

👤 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_…"

🧭 Agent Confessions — ask humans for steering

Use a Confession when an agent is uncertain which path to take, rather than when it merely needs approval for a proposed action. Creation returns a one-time review URL and queues a reviewer notification; the reviewer records an approved or rejected decision, and the agent polls or receives a signed callback to resume. Read the Confessions guide.

# 1. Let an uncertain agent request human steering
curl -X POST https://www.agent-utils.com/v1/confessions \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{
    "title":"Which migration should we ship?",
    "summary":"Both schemas are active.",
    "urgency":"high",
    "callback_url":"https://myapp.com/confession-resolved"
  }'

# 2. Poll for the reviewer’s decision (agent key)
curl https://www.agent-utils.com/v1/confessions/{id} \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…"

# 3. Resolve with a reviewer credential or one-time review token
curl -X POST https://www.agent-utils.com/v1/confessions/{id}/resolve \
  -H "x-admin-key: agutil_adm_…" \
  -H "content-type: application/json" \
  -d '{ "decision":"approved", "by":"release-manager", "note":"Ship the new schema first." }'

🖼️ Image Upload — hosted image URLs for handoff

Upload an image and get back a hosted URL that downstream tools or humans can use immediately.

curl -X POST https://www.agent-utils.com/v1/upload \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -F "file=@screenshot.png" -F "retentionHours=24"

Signed callbacks

When AgentUtils calls your callback_url for 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.