The handler package exposes 21 REST endpoints using the Forge router with full OpenAPI metadata. Routes are mounted under /v1/ and require an AppID in the request context.
Setup01
import (
"net/http"
"log/slog"
"github.com/xraph/chronicle/handler"
)
mux := http.NewServeMux()
api := handler.New(handler.Dependencies{
AuditStore: myStore,
VerifyStore: myStore,
ErasureStore: myStore,
RetentionStore: myStore,
ReportStore: myStore,
Compliance: complianceEngine,
Retention: retentionEnforcer,
Logger: slog.Default(),
}, mux)
api.RegisterRoutes(mux)
http.ListenAndServe(":8080", mux)Authentication02
Every request must have an AppID in the context (populated by your auth middleware). Requests without an AppID return 401 Unauthorized. TenantID is also enforced on all queries to prevent cross-tenant access.
Error format03
{"error": "chronicle: event not found"}Events04
| Method | Path | Description |
GET | /v1/events | List events with filters (category, action, severity, outcome, time range) |
GET | /v1/events/:id | Get a single event by ID |
GET | /v1/events/user/:userId | Get events for a specific user |
POST | /v1/events/aggregate | Grouped counts for analytics |
List events query parameters
| Parameter | Description |
category | Filter by event category |
action | Filter by action verb |
severity | info, warning, or critical |
outcome | success, failure, or denied |
from | Start time (RFC3339) |
to | End time (RFC3339) |
limit | Page size (default 20) |
offset | Page offset |
order | asc or desc |
Verification05
| Method | Path | Description |
POST | /v1/verify | Verify hash chain integrity |
Request body:
{
"stream_id": "stream_01j9vk...",
"from_seq": 0,
"to_seq": 0
}Response: verify.Report — valid, verified, gaps, tampered.
Erasure06
| Method | Path | Description |
POST | /v1/erasures | Request GDPR erasure for a subject |
GET | /v1/erasures | List erasure records |
GET | /v1/erasures/:id | Get a specific erasure record |
Retention07
| Method | Path | Description |
GET | /v1/retention | List retention policies |
POST | /v1/retention | Create or update a retention policy |
DELETE | /v1/retention/:id | Delete a policy |
POST | /v1/retention/enforce | Trigger immediate retention enforcement |
GET | /v1/retention/archives | List archive records |
Reports08
| Method | Path | Description |
GET | /v1/reports | List compliance reports |
POST | /v1/reports/soc2 | Generate SOC2 Type II report |
POST | /v1/reports/hipaa | Generate HIPAA report |
POST | /v1/reports/euaiact | Generate EU AI Act report |
POST | /v1/reports/custom | Generate custom report |
GET | /v1/reports/:id | Get a specific report |
GET | /v1/reports/:id/export/:format | Export report (json, csv, markdown, html) |
Stats09
| Method | Path | Description |
GET | /v1/stats | Aggregate statistics for audit events |
Forge extension10
When using the Forge extension, routes are registered automatically during Register unless WithDisableRoutes(true) is set:
ext := extension.New(
extension.WithStore(s),
// WithDisableRoutes defaults to false — routes are auto-registered
)
app.Register(ext)Access the underlying handler.API for manual control:
ext.API().RegisterRoutes(customRouter)Or get an http.Handler for standalone use:
h := ext.Handler()
http.ListenAndServe(":8080", h)