Admin Guide

This guide is for operators — the people keeping Hogsend running, managing contacts, debugging journeys, and maintaining email deliverability. If you're writing journey code, start with the Journeys page. If you need raw endpoint definitions, see the API Reference.

What the Admin API Gives You

The admin API (/v1/admin/*) is the operations control plane for your Hogsend instance. Through it you can:

• Manage contacts -- create, update, search, import/export, and view full activity timelines
• Operate journeys -- enable/disable without redeploying, inspect running instances, cancel stuck runs, manually enroll users
• Track email delivery -- browse send history, inspect delivery timelines, resend failed emails, monitor deliverability trends
• Monitor system health -- check component status, review real-time metrics, track event volume
• Set up alerts -- define threshold-based rules that notify you via Slack, webhook, or email when things go wrong
• Audit everything -- every admin mutation is automatically logged with actor, action, resource, and IP address

Architecture at a Glance

Hogsend runs as two processes from the same codebase:

                      +-------------------+
  HTTP requests  ---> |    API Process    | ---> Database (TimescaleDB)
                      |  (Hono on :3002)  | ---> Redis (caching)
                      +-------------------+
                             |
                     events pushed to
                             |
                             v
                      +-------------------+
                      |  Hatchet Engine   | <--- task orchestration
                      +-------------------+
                             |
                      +-------------------+
                      |  Worker Process   | ---> Resend (email delivery)
                      |  (Hatchet tasks)  | ---> PostHog (event capture)
                      +-------------------+

• The API process handles HTTP requests, authenticates admin keys, processes event ingestion, and pushes tasks to Hatchet.
• The Worker process executes durable tasks -- journey runs, email sends, bulk imports. It picks up work from the Hatchet queue and runs it reliably.
• Hatchet is the task orchestration engine that routes events to matching journeys, manages retries, and provides durable execution guarantees.
• TimescaleDB stores contacts, events, journey states, email records, audit logs, and all other persistent data.
• Redis is used for PostHog property caching and rate limiting.

Both processes share the same database, so admin API queries always reflect the latest state.

Getting Started

1. Get an API key

If you have the ADMIN_API_KEY environment variable set, you can use that immediately:

curl -H "Authorization: Bearer $ADMIN_API_KEY" \
  http://localhost:3002/v1/health

For production, create a scoped database-backed key (see Authentication):

curl -X POST http://localhost:3002/v1/admin/api-keys \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ops Dashboard", "scopes": ["read"] }'

2. Check system health

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:3002/v1/health

A healthy response looks like:

{
  "status": "healthy",
  "uptime": 12345.678,
  "components": {
    "database": { "status": "up", "latencyMs": 1 },
    "redis": { "status": "up", "latencyMs": 1 }
  }
}

3. View your journeys

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:3002/v1/admin/journeys

4. Check the overview metrics

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:3002/v1/admin/metrics/overview

Endpoint Quick Reference

All endpoints are prefixed with /v1/admin unless noted. Authentication is via Authorization: Bearer <api-key>.

Health & Metrics

Contacts

Journeys

Emails

Events

API Keys

Alerts & Monitoring

Next Steps