API overview

REST endpoints exposed by the grith daemon, organised by surface area.

The grith daemon (started by grith daemon start) binds on 127.0.0.1:3141 by default and exposes a REST API plus a WebSocket event stream.

Base URL & TLS

http://127.0.0.1:3141

By default grith binds to loopback only — there is no remote attack surface. To expose the API beyond loopback, either:

Configure [server.tls] with cert + key files, or
Front grith with a reverse proxy that terminates TLS — see Reverse proxy & TLS.

Authentication

For v0.1, the public endpoints accept any local caller. The IPC-only endpoints (/ipc/*) reject non-loopback connections at the listener.

When a Pro license is active, certain endpoints additionally require a valid plan-gate check; the call returns 403 PLAN_REQUIRED if the tier doesn't match.

Rate limits

[server.rate_limit] controls per-endpoint pacing:

General endpoints: 100 req/s
Write endpoints: 10 req/s
Proxy test: 20 req/s
IPC endpoints: uncapped (loopback only)

Exceeding the rate returns 429 RATE_LIMITED with a Retry-After header.

Endpoint groups

Health & tier

Liveness checks and license / plan-tier reporting.

Method	Path	Summary	Flags
GET	/health	Server liveness probe.
GET	/tier	Current plan tier and license expiry.
GET	/license/status	License validity and refresh state.
GET	/config	Read the active configuration.	local
PUT	/config	Update configuration values at runtime.	local

Audit

Persisted audit log of every filter decision.

Method	Path	Summary	Flags
GET	/audit	List audit events (paginated).
GET	/audit/export	Export audit events as JSON or CSV.
GET	/audit/exfil-stats	Aggregate exfiltration analytics over the recent window.
GET	/audit/{id}	Fetch one audit record.
POST	/ipc/audit/ingest	Internal IPC: ingest a batch of audit records.	IPC

Digest

The quarantine queue: ambiguous calls awaiting human review.

Method	Path	Summary	Flags
GET	/digest	List queued items.
GET	/ipc/digest/items/{id}	Fetch one digest item with full forensics.	IPC
POST	/digest/{id}/approve	Approve and execute.
POST	/digest/{id}/deny	Deny and block.
POST	/digest/{id}/learn	Approve and train the reputation system.
POST	/digest/{id}/escalate	Escalate to team (Pro).	Pro
POST	/digest/{id}/unlock-egress	Approve and whitelist the destination for this session.
POST	/digest/{id}/deny-terminate	Deny and kill the originating process tree.
POST	/digest/{id}/allow-always	Permanent allowlist for this call shape (Pro).	Pro
POST	/digest/{id}/webhook-review	Apply a decision delivered via webhook callback.

Proxy

Filter pipeline state and dry-run evaluation.

Method	Path	Summary	Flags
GET	/proxy/status	Filter stats, thresholds, and queue depth.
POST	/proxy/test	Dry-run a tool call shape. Returns the would-be decision.
POST	/proxy/evaluate	Internal IPC: evaluate a real syscall request.	IPC
GET	/proxy/status/full	Internal IPC: extended state including per-filter scores.	IPC

Supervisor sessions

Active supervised sessions and their lifecycle (IPC only).

Method	Path	Summary	Flags
GET	/ipc/sessions	List active supervisor sessions.	IPC
POST	/ipc/sessions	Register a new session.	IPC
GET	/ipc/sessions/{id}	Fetch session details.	IPC
PUT	/ipc/sessions/{id}	Update session metadata.	IPC
DELETE	/ipc/sessions/{id}	Unregister a session.	IPC
POST	/ipc/sessions/{id}/kill	Terminate a session and its process tree.	IPC

Canaries

Registered trap tokens that prove exfiltration if observed leaving the box.

Method	Path	Summary
GET	/canaries	List registered canary tokens.
POST	/canaries	Add a new canary token.
DELETE	/canaries/{id}	Remove a canary token.
POST	/canaries/{id}/rotate	Rotate the canary value while keeping its identity.

Notifications

Channel configuration and delivery health.

Method	Path	Summary
GET	/notifications/channels	List configured channels and their states.
GET	/notifications/status	Per-channel delivery health and recent failures.
POST	/notifications/test/{channel}	Send a synthetic notification to verify a channel.

Analytics

Aggregated usage, cost, and activity. Pro feature.

Method	Path	Summary	Flags
GET	/analytics/summary	Top-line stats: call volume, decisions split, cost.	Pro
GET	/analytics/cost	Provider cost breakdown by model and user.	Pro
GET	/analytics/activity	Call volume trends and per-session timelines.	Pro
GET	/analytics/compliance	Compliance-ready reporting bundles.	Ent

Sync & policies

Cloud-sourced team policies and shared filter configs. Pro feature.

Method	Path	Summary	Flags
GET	/sync/status	Cloud sync state and last successful pull.	Pro
GET	/sync/configs	List synced team configs.	Pro
POST	/sync/configs	Apply a synced config bundle to this device.	Pro
GET	/policies	List custom policies.	Pro
GET	/policies/{name}	Fetch one policy.	Pro
POST	/policies	Create a policy.	Pro
PUT	/policies/{name}	Update a policy.	Pro
DELETE	/policies/{name}	Delete a policy.	Pro

Reputation

Read and reset the adaptive trust table (IPC only).

Method	Path	Summary	Flags
GET	/reputation/table	Dump the current trust table.	IPC
POST	/reputation/observe	Record a single observation.	IPC
POST	/reputation/reset	Wipe learned trust (start over).	IPC
POST	/reputation/save	Force-flush the trust table to disk.	IPC

WebSocket

Real-time event stream for the dashboard.

Method	Path	Summary	Flags
GET	/events	Upgrade to a WebSocket. Streams digest, session, audit, and notification events.