j17 - Event sourcing for the rest of us

Manage specs, API keys, backups, and configure your instance via the Admin API. Admin operations are split between the headnode (identity, billing, spec deployment) and the worker (data operations proxied through 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

{ ... spec JSON ... }

Spec is validated before deployment. Invalid specs return 422 with error details.

Get current spec

The current spec for an instance/environment is served via the internal API (headnode-to-worker). Operators view specs 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 on the headnode and proxy to the appropriate worker node. All are 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 checkpoints capture all aggregates of a type at once:

Method	Endpoint	Description
`GET`	(internal) `/root-checkpoints`	List root checkpoints
`POST`	(internal) `/root-checkpoints`	Create root checkpoint
`GET`	(internal) `/root-checkpoints/latest`	Get latest root checkpoint
`DELETE`	(internal) `/root-checkpoints/:id`	Delete root checkpoint
`GET`	(internal) `/root-checkpoint-settings`	Get auto-checkpoint settings
`PUT`	(internal) `/root-checkpoint-settings`	Update auto-checkpoint 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`	(internal) `/blobs`	List blobs
`POST`	(internal) `/blobs`	Upload blob
`GET`	(internal) `/blobs/:name`	Get blob
`DELETE`	(internal) `/blobs/:name`	Delete 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 endpoints require node secret authentication (internal API only). They replace event payloads with tombstone markers while preserving stream structure.

Method	Endpoint	Description
`POST`	(internal) `/tombstone/:type/:id`	Create tombstone request
`GET`	(internal) `/tombstones`	List tombstones
`GET`	(internal) `/tombstones/:id`	Get tombstone status
`DELETE`	(internal) `/tombstones/:id`	Cancel (while pending)
`POST`	(internal) `/tombstones/:id/execute`	Execute tombstone

Tombstones have a configurable grace period (minimum 72 hours) before execution. After execution, event payloads are replaced with _was_tombstoned markers containing the original content hash. See the tombstones documentation for details on transitive cascade rules via onTombstone spec configuration.

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`	(internal) `/inject`	Inject test data (staging/test only)
`POST`	(internal) `/import`	Import historical events
`POST`	(internal) `/import_jsonl`	Import events in JSONL format
`POST`	(internal) `/cold_start`	Initial production data load
`GET`	(internal) `/export`	Export all events

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 and pushed from workers to the headnode.

Projections

Method	Endpoint	Description
`GET`	`/api/instances/:id/projections`	List configured projections

Admin API