REST API (v2)

Enable with CHRONACTA_REST_ENABLED=true (listen address CHRONACTA_REST_ADDRESS, default 127.0.0.1:8081).

The REST gateway is a thin JSON adapter over the local gRPC server. Operations and paths are defined in pkg/openapi/grpc-http-map.yaml and exposed as OpenAPI 3 at GET /v1/openapi.json.

Regenerate the checked-in spec:

make openapi-gen
make openapi-validate

Authentication

Same bearer token as gRPC. Pass Authorization: Bearer <token> on protected routes, or obtain a token via login:

curl -s -X POST http://127.0.0.1:8081/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"secret"}'

Endpoints

Method	Path	gRPC operation
GET	`/v1/health`	Health check
GET	`/v1/openapi.json`	OpenAPI document
POST	`/v1/auth/login`	Obtain bearer token
POST	`/v1/streams/{id}/append`	Append events (JSON body)
GET	`/v1/streams/{id}`	Read stream (forward, limit 100)
GET	`/v1/streams/{id}/info`	Stream metadata
GET	`/v1/admin/streams`	List streams
GET	`/v1/admin/verify`	Verify on-disk storage
GET	`/v1/admin/storage-status`	Engine status
GET	`/v1/admin/tenants`	List tenant usage
GET	`/v1/admin/tenants/{id}`	Tenant usage detail
POST	`/v1/admin/scavenge`	Retention scavenge (`dry_run` / `confirm`)

Append example

curl -s -X POST http://127.0.0.1:8081/v1/streams/orders/append \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"event_type":"OrderCreated","data":{"order_id":"1"}}'

Scavenge

Non-dry-run scavenge requires confirm: true in the JSON body.

SDKs

TypeScript: sdk/typescript (RestClient)
Python: sdk/python (chronacta.RestClient)

Contract tests: pkg/restgateway/contract_test.go (REST responses match gRPC for mapped operations).