Agent API

Bearer auth with an agent key (hb_conn_…): accounts, connections, queries, hash-chained audit, wallet, and relays.

Agents authenticate with their agent key — Authorization: Bearer hb_conn_… — minted at signup. The agent key never carries a data-source credential: the control plane resolves credentials server-side and rewrites scopes before any statement executes. Human sign-in sessions live in the dashboard and are separate.

Endpoint groups

Agent accounts & billing

Headless signup, usage metering, wallet topup, and pricing config.

POST /v1/agent/account
GET /v1/agent/account/usage
GET /v1/agent/billing/config
POST /v1/agent/topup
POST /v1/agent/webhook

Targets & packs

Discover connectors, their scope grammars, tables, and tiers.

GET /v1/connections/targets
GET /v1/connections/targets/{target_id}
GET /v1/connections/packs

Connections & queries

Scoped, TTL-bound connections with server-side scope rewrite.

POST /v1/connections
GET /v1/connections
GET /v1/connections/{connection_id}
POST /v1/connections/{connection_id}/query
POST /v1/connections/{connection_id}/revoke
GET /v1/connections/{connection_id}/audit

Audit evidence

Hash-chained audit verification — exits clean only if the chain is intact.

GET /v1/audit/verify?connection_id={connection_id}

Production credentials

Bring your own account credentials (e.g. a read-only Stripe restricted key).

GET /v1/connections/credentials/kinds
GET /v1/connections/credentials
POST /v1/connections/credentials
DELETE /v1/connections/credentials/{connector_kind}

Relays (customer-side)

Enroll customer Postgres behind an outbound-only mTLS tunnel.

POST /v1/relays/enroll-token
POST /v1/relays/register
GET /v1/relays
POST /v1/relays/{relay_id}/renew
POST /v1/relays/{relay_id}/rotate-cert
DELETE /v1/relays/{relay_id}

First requests

The 90-second flow, verified against the live API:

POST /v1/agent/account          {"orgName":"my-agent","agentName":"my-agent","headless":true}
# → 201 {"apiKey":"hb_conn_…","orgId":"…","trial":{"queries":100,"egressBytes":5000000}}

GET  /v1/connections/targets    # 20 targets (12 demo + 8 live) + scopes per target

POST /v1/connections            {"target_id":"demo-postgres-audit",
                                 "scopes":["gl:read","period:2025-Q4"],
                                 "tier":"container","ttl_seconds":3600}
# → 201 {"connectionId":"…","audit_genesis_hash":"…"}

POST /v1/connections/{id}/query {"sql":"SELECT * FROM gl LIMIT 10"}
# → 200 {"rows":[…],"cost_cents":2,"audit_event_id":"…","scope_applied":{…}}

GET  /v1/audit/verify?connection_id={id}
# → 200 {"verified":true,"events_checked":2,"broken_at":null}

Costs on every response

Query responses return cost_cents and bytes_egressed. The trial includes 100 queries and 5 MB of egress over 7 days with $1 of credit — no card required. After that it's $0.005 per query and $0.08 per GB; a prepaid wallet with optional auto-reload covers usage. See pricing.

What the API does not own

Endpoints such as /v1/auth/status and key management UI return 501 from the Hebrah API — those are owned by the dashboard at http://localhost:3000.

Where to go next

Connectors — every target and its scope grammar
Relay — customer-side enrollment for your own Postgres
MCP — the same surface as agent tools