API overview
Every AgentPack route is a POST with a JSON body. Authentication is one
of three headers:
| Header | Carries | Used by |
|---|---|---|
x-agentpack-key | Project bridge key | MTA, operators |
x-agentpack-device-key | Per-agent device key | Agents |
x-agentpack-delegation | Delegation token | Cross-agent calls |
Replies are JSON on success. Failures return RFC 7807 problem+json:
{
"type": "https://agentpack.dev/errors/scope_mismatch",
"title": "scope mismatch",
"status": 403,
"detail": "device key bound to 'agent-hello' cannot act for 'agent-triage'"
}
Idempotency
Writes use ON CONFLICT or existence checks, so retrying a 5xx is
safe. The only exception is /send: a duplicate /send is a new
delivery, not a replay. Callers that need exactly-once outbound should
include their own idempotency key in the body and dedupe on the server.
Versioning
Routes are stable within a major version. Breaking changes are gated on
Accept-Version: 2 style headers and shipped alongside a migration
runbook in the release notes.