j17 - Event sourcing for the rest of us

Manage specs, API keys, backups, and configure your instance via the Admin API. All admin endpoints use JWT authentication on the headnode.

Authentication

All admin endpoints require JWT authentication on the headnode:

curl https://control.j17.dev/api/instances \
  -H "Authorization: Bearer $JWT_TOKEN"

Get a JWT via login:

curl -X POST https://control.j17.dev/api/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "..."}'

Spec management

Deploy spec

POST /api/instances/:instance_id/spec
Authorization: Bearer $JWT
Content-Type: application/json

{
  "environment": "prod",
  "spec": {
    "aggregate_types": { ... },
    "agent_types": [ ... ]
  }
}

The spec goes inside the "spec" key. The dashboard upload expects the same format.

Specs are validated before deployment. Invalid specs return 422 with error details. Incompatible changes (removing types, changing required fields) are rejected unless "force": true is passed (non-prod environments only).

Get current spec

The current spec is available through the dashboard UI.

API key management

All key management is on the headnode.

List keys

GET /api/instances/:instance_id/keys
Authorization: Bearer $JWT

Create key

POST /api/instances/:instance_id/keys
Authorization: Bearer $JWT

{
  "name": "Production Backend",
  "scope": "write",
  "environment": "prod"
}

Response includes the key (shown once):

{
  "id": "key-uuid",
  "name": "Production Backend",
  "key": "j17_0_prod_xyz789...",
  "scope": "write",
  "environment": "prod",
  "created_at": "2024-01-15T10:00:00Z"
}

Rotate key

POST /api/keys/:id/rotate
Authorization: Bearer $JWT

Creates a new key and revokes the old one.

Schedule revocation

POST /api/keys/:id/schedule_revocation
Authorization: Bearer $JWT

{
  "revoke_at": "2024-02-01T00:00:00Z"
}

Revoke key

DELETE /api/keys/:id
Authorization: Bearer $JWT

Revoked keys fail immediately on next use.

Instance operations

These endpoints are all under /api/instances/:id/ops/:environment/.

Checkpoints

Checkpoints snapshot aggregate state for faster replay.

Method	Endpoint	Description
`GET`	`/ops/:env/checkpoints`	List checkpoints
`POST`	`/ops/:env/checkpoints`	Create checkpoint
`POST`	`/ops/:env/checkpoints/:checkpoint_id/restore`	Restore checkpoint
`DELETE`	`/ops/:env/checkpoints/:checkpoint_id`	Delete checkpoint

Root anchors capture Merkle roots for cryptographic verification:

Method	Endpoint	Description
`GET`	`/ops/:env/root_anchors`	List root anchors
`POST`	`/ops/:env/root_anchors`	Create root anchor
`DELETE`	`/ops/:env/root_anchors/:id`	Delete root anchor
`PUT`	`/ops/:env/anchor_schedule`	Update auto-anchor schedule
`GET`	(internal) `/root-anchors/latest`	Get latest root anchor
`GET`	(internal) `/root-anchor-settings`	Get full anchor settings

Backups

Method	Endpoint	Description
`GET`	`/ops/:env/backups`	List backups
`POST`	`/ops/:env/backups`	Create backup
`DELETE`	`/ops/:env/backups/:backup_id`	Delete backup

Backup settings (offsite S3 configuration):

Method	Endpoint	Description
`GET`	`/api/instances/:id/backup_settings`	Get backup settings
`PUT`	`/api/instances/:id/backup_settings`	Update backup settings

Blobs

Binary data storage (e.g., WASM modules, config files).

Method	Endpoint	Description
`GET`	`/ops/:env/blobs`	List blobs
`DELETE`	`/ops/:env/blobs/:name`	Delete blob
`POST`	(internal) `/blobs`	Upload blob
`GET`	(internal) `/blobs/:name`	Get blob

Scheduled events

Method	Endpoint	Description
`GET`	(internal) `/scheduled`	List scheduled events
`POST`	`/ops/:env/scheduled/:event_id/cancel`	Cancel scheduled event
`POST`	`/ops/:env/scheduled/:event_id/retry`	Retry failed event
`GET`	(internal) `/scheduled/dead`	List dead letters

Sagas

Method	Endpoint	Description
`GET`	(internal) `/sagas`	List sagas
`GET`	(internal) `/sagas/:saga_id`	Get saga detail
`POST`	`/ops/:env/sagas/:saga_id/retry`	Retry failed saga

Tombstones (GDPR erasure)

Tombstone operations are managed through the dashboard. See the tombstones reference for how tombstoning works and how to configure onTombstone cascade rules in your spec.

Listener deliveries (webhooks)

Listeners deliver events to HTTP endpoints with HMAC-SHA256 signed payloads. Failed deliveries retry with exponential backoff (5s, 25s, 125s) up to 3 attempts.

Method	Endpoint	Description
`GET`	(internal) `/deliveries`	List listener deliveries

Listeners are configured in your spec, not via API. The delivery system handles: - Automatic retry with exponential backoff - HMAC-SHA256 payload signing (X-J17-Signature header) - Delivery cleanup (delivered > 7 days, failed > 30 days)

Audit

Cryptographic verification of event integrity.

Method	Endpoint	Description
`GET`	(internal) `/audit/merkle-root/:type/:id`	Get Merkle root for aggregate
`GET`	(internal) `/audit/merkle-proof/:type/:id/:index`	Get Merkle proof for event
`POST`	(internal) `/audit/merkle-verify`	Verify Merkle proof
`GET`	(internal) `/audit/verify-chain/:type/:id`	Verify hash chain integrity

These are also available via API key auth at /:type/:id/audit/....

Data loading

Method	Endpoint	Description
`POST`	`/ops/:env/inject`	Inject test data (staging/test only)
`POST`	`/ops/:env/import`	Import historical events (`mode=append` or `mode=replace`; `replace` is non-prod only)
`POST`	(internal) `/import_jsonl`	Import events in JSONL format
`POST`	(internal) `/cold_start`	Initial production data load
`GET`	(internal) `/export`	Export all events

Data reset

Wipe all events, aggregates, projections, sagas, and scheduled events for an environment. Restricted to staging and test — calling this on prod returns 403.

POST /api/instances/:id/ops/:environment/reset
Authorization: Bearer $JWT

No request body. Returns { "ok": true } on success. Requires the instance_admin role.

This is destructive and irreversible — there is no undo. Use it to recycle non-prod environments between test runs or after spec changes that aren't backwards-compatible with existing event data.

Error lookup

GET /api/instances/:id/ops/:environment/errors/:error_id
Authorization: Bearer $JWT

Returns details for a specific error, including the full error context and stack trace.

Usage and billing

Usage and billing endpoints are on the headnode.

Method	Endpoint	Description
`GET`	`/api/instances/:id`	Instance details including plan/tier

Usage metrics are tracked per instance.

Projections

Method	Endpoint	Description
`POST`	`/api/instances/:id/projections`	Deploy a projection definition
`GET`	`/api/instances/:id/projections`	List configured projections
`DELETE`	`/api/instances/:id/projections/:name`	Remove a projection

The deploy body wraps the definition:

{
  "name": "order_summary",
  "environment": "prod",
  "projection": {
    "for_each": "order",
    "sources": {"order": "$key"},
    "select": {"total": "$.order.total"}
  }
}

See the projections guide for full details on sources, select transforms, and SQL queries.

Admin API