API Reference

Hogsend exposes a REST API built on Hono with Zod OpenAPI for request/response validation. The HTTP server is the @hogsend/engine app your scaffolded src/index.ts builds with createApp(container, { webhookSources }) — the engine ships the routes; your app injects the content. All endpoints are versioned under /v1.

Base URL

http://localhost:3002   # local development
https://api.hogsend.com # production

Interactive Docs

In non-production environments, the API serves an auto-generated OpenAPI spec and an interactive Scalar UI:

These endpoints are disabled when NODE_ENV=production.

Authentication

Hogsend uses two authentication mechanisms depending on the endpoint:

Better Auth (session-based)

Studio and user-facing endpoints use Better Auth with email/password authentication. Auth routes are mounted at /api/auth/*:

• Email and password sign-in (passwords 8–128 chars). Public sign-up is disabled (disableSignUp) — POST /api/auth/sign-up/email returns 400 EMAIL_PASSWORD_SIGN_UP_DISABLED for everyone, including the in-process auth.api.signUpEmail. There is no setup token and no web create-admin form.
• Session-based auth with 7-day expiry (refreshed daily)
• Self-service forgot/reset password (single-use token, 15-min TTL) — live only when a reset mailer is wired
• Organization plugin (up to 5 orgs, 100 members each)

Because public sign-up is closed, the first Studio admin is created from your server — run hogsend studio admin create (needs DATABASE_URL + BETTER_AUTH_SECRET in the environment), or set STUDIO_ADMIN_EMAIL (+ optional STUDIO_ADMIN_PASSWORD) and the API mints it on boot into an empty user table. A zero-user instance renders a read-only info screen, not a create form. See Authentication for the full model.

API Keys (bearer token)

Both the admin plane (/v1/admin/*) and the public data plane (/v1/contacts, /v1/events, /v1/emails, /v1/lists) use bearer-token API keys. The data plane is bearer-authed but it is not under /v1/admin — it's a separate surface gated by a separate scope (see below and the Data API). Hogsend supports two auth modes:

1. Legacy key -- A static key from the ADMIN_API_KEY environment variable (full admin access; implies ingest)
2. Database-backed keys -- Generated via POST /v1/admin/api-keys with scoped permissions

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

Keys are SHA-256 hashed before storage -- the raw key is only shown once at creation time. Scopes come in two kinds:

The three admin scopes are hierarchical: read < journey-admin < full-admin, each implying the ones below it. ingest is orthogonal — it sits outside that ladder. A read or journey-admin key does not get ingest, and an ingest-only key does not get admin access. The only ways to reach the data plane are an explicit ingest grant or full-admin. Combine scopes (e.g. ["read", "ingest"]) for a key that needs both planes.

Keys can be revoked and have optional expiry dates. Active keys are cached in memory for 60 seconds.

If neither ADMIN_API_KEY nor any database-backed keys are configured, admin endpoints return 503 Service Unavailable.

Middleware Stack

The app is built by createApp(container, opts) (from @hogsend/engine). Every request passes through the following built-in global middleware in order:

1. Container injection -- Sets the DI container on the Hono context
2. Secure headers -- Adds security-related HTTP headers
3. CORS -- Cross-origin resource sharing (permissive by default)
4. Compression -- gzip/brotli response compression
5. Request ID -- Generates a unique X-Request-Id header
6. Request logger -- Logs method, path, status, and duration

Any custom middleware: MiddlewareHandler[] you pass to createApp is applied after this built-in stack. Thrown errors are caught by a built-in error handler (overridable via the onError option) that returns JSON { error } with the appropriate status code.

The following middleware is scoped to the admin router (/v1/admin/*), not the global stack:

• Rate limiter -- Sliding window (100 req/min per key) with Redis backend and in-memory fallback
• Audit logger -- Records all admin mutations (POST/PUT/PATCH/DELETE) with actor, action, resource, and IP

Error Responses

All errors follow this shape:

{
  "error": "Human-readable error message"
}

• 400 -- Validation error (Zod schema mismatch)
• 401 -- Missing or invalid authentication
• 404 -- Resource not found
• 409 -- Conflict (e.g., duplicate externalId)
• 429 -- Rate limit exceeded
• 500 -- Internal server error (message is generic in production)
• 503 -- Service not configured

Environment Variables

The engine validates all environment variables at startup using @t3-oss/env-core with Zod schemas. The server will not start if required variables are missing. In a scaffolded app these live in its own root .env (copied from .env.example), not in any monorepo path.

API Sub-pages