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 console API.

Authentication

All admin endpoints require JWT authentication on the console API:

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

Get a JWT via login:

curl -X POST https://console.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).

This is the JWT path on the console API. To deploy from CI with just an API key — no JWT, same host as your reads and writes — use a deploy-scoped key against POST /_spec on your instance. See Schema Deployment.

Get current spec

The current spec is available through the dashboard UI.

API key management

All key management is on the console API.

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

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

Scheduled events

Method	Endpoint	Description
`POST`	`/ops/:env/scheduled/:event_id/cancel`	Cancel scheduled event
`POST`	`/ops/:env/scheduled/:event_id/retry`	Retry failed event

Sagas

Method	Endpoint	Description
`POST`	`/ops/:env/sagas/:saga_id/retry`	Retry failed saga

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. Delivery history is viewable in the dashboard.

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, on your instance with API key auth:

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

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`	`/ops/:env/cold_start`	Seed a fresh environment once, refused if it already holds data

import changes data at any time (append, or replace to wipe first); cold_start seeds an empty environment exactly once and then latches it — a second call returns 409. Both take { "events": [...] }. Use cold_start to provision an environment from an export, import to change data that already exists. The same "seed a fresh environment" verb is available to a deploy-scoped API key (no console login) — see Schema Deployment.

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 console API.

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.

These are the JWT endpoints on the console API. To deploy or delete projections with a deploy-scoped API key on your instance, see Schema Deployment.

Admin API