API Reference

Current hosted control-plane API surface for sample runs, runs, agents, rulesets, events, approvals, keys, and notifications.

Edictum Control Plane exposes a ruleset-centric hosted API. The current public surface is built around runs, agents, rulesets, events, approvals, keys, and notification channels.

Auth

All documented /v1/* routes require Authorization: Bearer <token> unless noted otherwise.
Agent traffic uses workspace API keys with the edk_ prefix.
Operator traffic uses Clerk bearer tokens.
GET /v1/events/stream may also use the API's HttpOnly edictum_session cookie in browser contexts.
POST /v1/approvals/{id}/decide requires a Clerk-authenticated operator identity. The backend records the verified operator and ignores client-supplied decided_by.

Sample Run

Method	Path	Purpose
`POST`	`/v1/sample-run`	Trigger the seeded sample governed run for the authenticated workspace. Repeat calls reuse the same sample run instead of creating duplicates.

The response includes the created or reused agent_id, session_id, run_id, ruleset_name, and approval_id.

Runs

Method	Path	Purpose
`GET`	`/v1/runs`	List workspace runs. Supports `status`, `agent_id`, `session_id`, `limit`, and `offset`.
`GET`	`/v1/runs/{agent_id}/{session_id}/bundle`	Download the signed decision bundle for one run session.

GET /v1/runs is the main runs overview. Each row includes workflow state, ruleset_name, ruleset_version, last activity, and pending approval state.

Agents

Method	Path	Purpose
`GET`	`/v1/agents`	List registered agents for the current workspace.
`GET`	`/v1/agents/{id}`	Get one agent plus health summary and recent runs.
`GET`	`/v1/agents/{id}/workflow-state`	Get the latest materialized workflow snapshot for one agent session. Requires `session_id`.

Notes:

health.status is one of healthy, stale, blocked, or approval_pending.
recent_runs uses the same shape as the runs list.
workflow-state is session-scoped, not agent-global.

Rulesets

Method	Path	Purpose
`GET`	`/v1/rulesets`	List rulesets in the current workspace.
`GET`	`/v1/rulesets/{name}`	Get the latest stored version of one ruleset.
`PUT`	`/v1/rulesets/{name}`	Upload a new version for one ruleset name.
`GET`	`/v1/rulesets/{name}/versions`	List saved versions for one ruleset, newest first.
`GET`	`/v1/rulesets/{name}/versions/{version}`	Get one exact saved version.
`GET`	`/v1/rulesets/{name}/current`	Get the currently deployed ruleset content for that name.
`GET`	`/v1/rulesets/{name}/replay`	Replay recent sessions against two saved ruleset versions.

The current hosted API is ruleset-first. The older rule-library, composition, and bundle management routes are not part of the live public surface.

Ruleset Upload

Upload raw YAML to PUT /v1/rulesets/{name} with Content-Type: application/x-yaml.

The YAML must be a real Edictum ruleset:

apiVersion: edictum/v1
kind: Ruleset
metadata:
  name: default
rules:
  - id: block-dotenv
    type: pre
    tool: read_file
    when:
      args.path:
        contains: '.env'
    then:
      action: block
      message: 'Sensitive file blocked.'

Events

Method	Path	Purpose
`POST`	`/v1/events`	Ingest a batch of agent decision events. Request body shape: `{ "events": [...] }`.
`GET`	`/v1/events`	List workspace decision events. Supports `agent_id`, `session_id`, `parent_session_id`, `decision`, `since`, `until`, `limit`, and `offset`.
`GET`	`/v1/events/stream`	Stream workspace-scoped decision events over SSE. Supports `agent_id` and `session_id`.

GET /v1/events/stream streams the same decision event shape returned by GET /v1/events.

Audit

Method	Path	Purpose
`GET`	`/v1/audit`	List the workspace audit feed across approvals, keys, ruleset deployments, and run decisions.

Supported audit query params:

from, to
actor
repeated action_type
subject_type
limit
cursor

Approvals

Method	Path	Purpose
`POST`	`/v1/approvals`	Create a pending approval. This is the agent-side path used by approval backends.
`GET`	`/v1/approvals`	List approvals. Supports `status`, `agent_id`, `session_id`, `limit`, and `offset`.
`GET`	`/v1/approvals/{id}`	Get one approval by ID.
`POST`	`/v1/approvals/{id}/decide`	Approve or reject one pending approval.

The current approval object uses rule_name.

Approval Shape

{
  "id": "uuid",
  "agent_id": "my-agent",
  "session_id": "run-123",
  "tool_name": "delete_user",
  "tool_args": { "user_id": "u_123" },
  "message": "Agent wants to delete user account",
  "rule_name": "require-human-review",
  "status": "pending",
  "timeout": 300,
  "timeout_action": "block",
  "created_at": "2026-03-01T12:00:00Z"
}

Approval Decision Request

{
  "decision": "approved",
  "decided_via": "control plane",
  "reason": "Reviewed locally"
}

Valid decision values are approved and rejected.

API Keys

Method	Path	Purpose
`GET`	`/v1/keys`	List workspace API keys.
`POST`	`/v1/keys`	Create a workspace API key. The raw key is returned once.
`DELETE`	`/v1/keys/{id}`	Revoke one key.

Key creation request:

{
  "name": "pilot"
}

Notification Channels

Method	Path	Purpose
`GET`	`/v1/notifications/channels`	List notification channels.
`POST`	`/v1/notifications/channels`	Create a channel.
`PUT`	`/v1/notifications/channels/{id}`	Update a channel.
`DELETE`	`/v1/notifications/channels/{id}`	Delete a channel.
`POST`	`/v1/notifications/channels/{id}/test`	Send a test notification.

Channel types currently supported:

telegram
slack
discord
webhook

The current request shape is:

{
  "name": "Ops Telegram",
  "channel_type": "telegram",
  "enabled": true,
  "config": {
    "bot_token": "123:ABC",
    "chat_id": "-1001234567890"
  },
  "filters": {}
}

interactive is currently true only for Telegram.

Telegram Webhook

Method	Path	Purpose
`POST`	`/v1/telegram/webhook/{id}`	Handle Telegram callback button decisions for one channel.

This is a public callback route. Telegram verification happens through the webhook secret token header.

No Dedicated Diff Endpoint

The current backend does not expose a dedicated ruleset diff route.

The frontend compares versions by fetching:

GET /v1/rulesets/{name}/versions/{from}
GET /v1/rulesets/{name}/versions/{to}

and diffing the returned YAML locally.

On this page