Reference

CLI Tree

The complete CLI tree is rendered by ChatStyle. See CLI Tree. chatevent --tree is the full view with parameter signatures, while chatevent --tree-brief is the compact view without signatures; both are shared by docs and tests.

HTTP API

Method	Path	Purpose
GET	/api/health	Health check and current SQLite DB path.
POST	/api/login	Username/password Web login; sets browser cookie.
POST	/api/logout	Clear browser cookie.
GET	/api/session	Return current API token or cookie identity.
GET	/api/users	Admin-only user list.
POST	/api/users	Admin creates a username/password user.
POST	/api/me/token	Current account issues a one-time arch_xxx API token.
POST	/api/users/{id}/token	Admin issues a one-time API token for a user.
DELETE	/api/users/{id}	Admin deletes a user.
GET	/api/schema/event	Return the ChatEvent JSON Schema.
GET	/api/schema/subscription	Return the Subscription JSON Schema.
GET	/api/platforms	Return the platform action catalog.
POST	/api/subscriptions	Create or update a subscription.
GET	/api/subscriptions	List subscriptions.
DELETE	/api/subscriptions/{id}	Delete a subscription without deleting captured events.
POST	/api/events	Record one normalized ChatEvent.
GET	/api/events	Query events with source, kind, subscription, keyword, since checkpoint, recent-day, and captured-at range filters.
GET	/api/events/{dedupe_key}	Read one stored event.
GET	/api/stats	Return event/source/duplicate statistics.
POST	/webhooks/zulip	Receive Zulip event-queue/message payloads.
POST	/webhooks/discourse	Receive Discourse webhook payloads.
POST	/webhooks/gitea	Receive Gitea webhook payloads.
POST	/webhooks/github	Receive GitHub webhook payloads.

CLI and REST API mapping

chatevent api ... is the command-line client for the REST API. It reads CHATEVENT_API_URL by default and falls back to http://127.0.0.1:8765.

CLI	REST API
chatevent api health	GET /api/health
chatevent api stats	GET /api/stats
chatevent api platforms	GET /api/platforms
chatevent api schema event	GET /api/schema/event
chatevent api subscriptions	GET /api/subscriptions
chatevent api subscription <id>	GET /api/subscriptions/{id}
chatevent api events --source discourse --days 7	GET /api/events?...
chatevent api event <dedupe_key>	GET /api/events/{dedupe_key}
chatevent api record-json event.json	POST /api/events
chatevent api save-subscription subscription.json	POST /api/subscriptions
chatevent api delete-subscription <id>	DELETE /api/subscriptions/{id}

Action and carrier target fields

Both ChatEvent and Subscription support structured action targets while keeping old fields compatible:

• Subscription.target: canonical string for display and hand-written config.
• Subscription.scope: structured carrier target with type, key, display, url, parent, and metadata; type is open-ended.
• Subscription.actions: structured action selectors; if only event_kinds is provided, the service derives them automatically.
• ChatEvent.action: concrete action with kind, object_type, verb, and metadata.
• ChatEvent.actor / actor_role: initiator and platform-specific role; role stays an open string, e.g. maintainer, member, bot, or moderator.
• ChatEvent.target: concrete object acted on; parent links repo/PR/comment or stream/topic/message carrier chains.

Old clients that only send kind, subject_id, and subject_type remain valid. New adapters write full action and target whenever possible.

Query events

curl -k 'https://event.public.wzhecnu.cn/api/events?source=discourse&kind=reply.created&days=7&limit=20'

Downstream systems consume by checkpoint:

curl -k 'https://event.public.wzhecnu.cn/api/events?source=discourse&subscription_id=discourse-practice&since=2026-08-18T12:47:37Z&limit=50'

Common parameters:

Parameter	Meaning
source	Platform source such as discourse.
kind	Event kind such as reply.created.
subscription_id	Subscription id.
since	Consumer checkpoint: return only events with captured_at > since; timezone is required, e.g. 2026-08-18T12:47:37Z.
days	Shortcut date filter: return events captured in the last N days, e.g. days=7.
from	Captured-at range start: return events with captured_at >= from; timezone is required.
to	Captured-at range end: return events with captured_at <= to; timezone is required.
q	Keyword search across payload, actor, and conversation fields.
limit	Number of events to return, from 1 to 500.

Responses include items, count, latest_captured_at, and next_since. Consumers should save next_since after successful processing and send it as since on the next poll. The Observatory uses days for the last 24 hours / 3 days / 7 days / 30 days presets, and from/to for custom ranges.

Deduplication

The default dedupe key is:

source:id

Repeated delivery of the same event does not create a new row; it increments seen_count and contributes to /api/stats duplicate_count.

Storage and online editing

Subscription configuration and the event ledger are stored in SQLite. The default database is inside ChatEnv/ChatArch home:

<chatarch-home>/chatevent/events.db

Path precedence is --db, CHATEVENT_DB, ChatEnv get_paths().home_dir/chatevent/events.db, $CHATARCH_HOME/chatevent/events.db, then ~/.chatarch/chatevent/events.db. On first default-path use, if legacy ~/.chatevent/events.db exists and the new database does not, ChatEvent copies it into the ChatArch-internal path and keeps the legacy file.

subscriptions.body stores the full Subscription JSON, including last_cursor and last_event_at updates after events arrive; events.body stores the full ChatEvent JSON.

The Web Observatory Subscriptions tab can create, edit, enable/disable, and delete subscriptions. Production or public deployments should configure user login and may keep a bootstrap API token: CHATEVENT_ADMIN_TOKEN first, then CHATEVENT_ADMIN_TOKEN_FILE, then the default file $CHATARCH_HOME/chatevent/secrets/admin-token or ~/.chatarch/chatevent/secrets/admin-token. The bootstrap token is for API/CLI initialization or recovery only; it is not a Web login credential.

Login, User Management, And Isolation

ChatEvent now uses a minimal username/password + API token model:

• GET /: when users or bootstrap credentials are configured, unauthenticated callers receive only the username/password login page; authenticated callers receive the Observatory.
• POST /api/login: validate username / password and set a browser cookie.
• POST /api/logout: clear the browser cookie.
• GET /api/session: validate the current X-ChatEvent-Admin-Token or cookie and return admin_required, authenticated, user, and whether the caller is the bootstrap admin.
• GET /api/users: list users as an administrator.
• POST /api/users: create a username/password user; the server stores only the password hash.
• POST /api/me/token: issue a one-time arch_xxx API token for the current logged-in account.
• POST /api/users/{id}/token: issue a one-time API token for a target user as an administrator.
• DELETE /api/users/{id}: delete a user as an administrator.

After an admin token or users exist, read APIs such as /api/stats, /api/events, /api/events/{dedupe_key}, schema, platforms, and subscriptions require login. Event-write and webhook endpoints remain reachable so platform events can still arrive.

CHATEVENT_BOOTSTRAP_USERNAME and CHATEVENT_BOOTSTRAP_PASSWORD_FILE can initialize the first administrator account. CHATEVENT_ADMIN_TOKEN / secrets/admin-token is the bootstrap administrator API credential for CLI/model/API user creation or recovery. Subscription.owner_user_id is the current isolation boundary: subscriptions created by member accounts are automatically owned by that user; members can only read, update, and delete their own subscriptions; admins can manage all subscriptions. The event stream remains an Observatory debugging view for now and can be tightened by tenant/user owner later.