PraisonAIUI uses a protocol-driven architecture to wire features into the server. Every feature module implements the BaseFeatureProtocol ABC, which auto-registers API routes, CLI commands, and health checks.
BaseFeatureProtocol
Every feature module must implement:
| Method | Return | Required | Description |
|--------|--------|----------|-------------|
| name | str | ✓ | Unique feature identifier |
name
str
| description | str | ✓ | Human-readable description |
description
| routes() | List[Route] | ✓ | Starlette routes to mount |
routes()
List[Route]
| cli_commands() | List[dict] | ○ | CLI command metadata |
cli_commands()
List[dict]
| health() | dict | ○ | Health check (default: {"status": "ok"}) |
health()
dict
{"status": "ok"}
| info() | dict | ○ | Metadata for /api/features listing |
info()
/api/features
Tool-execution approval management with policies, history, and SSE streaming.
| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/approvals | GET | List all approvals |
/api/approvals
| /api/approvals | POST | Create approval request |
| /api/approvals/pending | GET | List pending approvals |
/api/approvals/pending
| /api/approvals/history | GET | List resolved approvals |
/api/approvals/history
| /api/approvals/policies | GET | Get auto-approve/deny policies |
/api/approvals/policies
| /api/approvals/policies | PUT | Update policies |
| /api/approvals/stream | GET | SSE stream for real-time updates |
/api/approvals/stream
| /api/approvals/{id} | GET | Get single approval |
/api/approvals/{id}
| /api/approvals/{id}/approve | POST | Approve request |
/api/approvals/{id}/approve
| /api/approvals/{id}/deny | POST | Deny request |
/api/approvals/{id}/deny
CLI: aiui approval list, aiui approval pending
aiui approval list
aiui approval pending
Multi-platform messaging channel management (Discord, Slack, Telegram, WhatsApp, etc.).
| /api/channels | GET | List all channels (enriched with gateway status) |
/api/channels
| /api/channels | POST | Add a channel |
| /api/channels/platforms | GET | List supported platforms |
/api/channels/platforms
| /api/channels/{id} | GET | Get channel details |
/api/channels/{id}
| /api/channels/{id} | PUT | Update channel |
| /api/channels/{id} | DELETE | Remove channel |
| /api/channels/{id}/toggle | POST | Enable/disable |
/api/channels/{id}/toggle
| /api/channels/{id}/status | GET | Live status (gateway-enriched) |
/api/channels/{id}/status
| /api/channels/{id}/restart | POST | Restart channel bot (via gateway) |
/api/channels/{id}/restart
CLI: aiui channel list, aiui channel status, aiui channel platforms
aiui channel list
aiui channel status
aiui channel platforms
Manage scheduled jobs (cron, interval, one-shot).
| /api/schedules | GET | List all jobs |
/api/schedules
| /api/schedules | POST | Add a job |
| /api/schedules/{id} | GET | Get job details |
/api/schedules/{id}
| /api/schedules/{id} | PUT | Update schedule config |
| /api/schedules/{id} | DELETE | Remove job |
| /api/schedules/{id}/toggle | POST | Enable/disable |
/api/schedules/{id}/toggle
| /api/schedules/{id}/run | POST | Trigger immediately |
/api/schedules/{id}/run
| /api/schedules/{id}/stop | POST | Stop running schedule |
/api/schedules/{id}/stop
| /api/schedules/{id}/stats | GET | Get execution statistics |
/api/schedules/{id}/stats
CLI: aiui schedule list, aiui schedule add <name> <msg>, aiui schedule remove <id>, aiui schedule status
aiui schedule list
aiui schedule add <name> <msg>
aiui schedule remove <id>
aiui schedule status
Agent memory management (short-term, long-term, entity).
| /api/memory | GET | List memories (filter: ?type=short\|long\|entity\|all) |
/api/memory
?type=short\|long\|entity\|all
| /api/memory | POST | Add memory entry |
| /api/memory/search | POST | Search memories |
/api/memory/search
| /api/memory/{id} | GET | Get single memory |
/api/memory/{id}
| /api/memory/{id} | DELETE | Delete memory |
| /api/memory | DELETE | Clear memories (filter: ?type=all) |
?type=all
CLI: aiui memory list, aiui memory add <text>, aiui memory search <query>, aiui memory clear, aiui memory status
aiui memory list
aiui memory add <text>
aiui memory search <query>
aiui memory clear
aiui memory status
Execution node registration, agent bindings, and instance presence.
| /api/nodes | GET | List all nodes |
/api/nodes
| /api/nodes | POST | Register a node |
| /api/nodes/{id} | GET | Get node details |
/api/nodes/{id}
| /api/nodes/{id} | PUT | Update node |
| /api/nodes/{id} | DELETE | Remove node |
| /api/nodes/{id}/status | GET | Node status (gateway-enriched) |
/api/nodes/{id}/status
| /api/nodes/{id}/agents | GET/PUT | Get/set agent bindings |
/api/nodes/{id}/agents
| /api/instances | GET | List connected instances |
/api/instances
| /api/instances/heartbeat | POST | Record presence heartbeat |
/api/instances/heartbeat
CLI: aiui node list, aiui node status, aiui node instances
aiui node list
aiui node status
aiui node instances
Advanced session management (state, context, labels, usage).
| /api/sessions/{id}/state | GET | Get session state |
/api/sessions/{id}/state
| /api/sessions/{id}/state | POST | Save session state |
| /api/sessions/{id}/context | POST | Build context |
/api/sessions/{id}/context
| /api/sessions/{id}/compact | POST | Compact session (with stats) |
/api/sessions/{id}/compact
| /api/sessions/{id}/reset | POST | Reset session |
/api/sessions/{id}/reset
| /api/sessions/{id}/preview | GET | Formatted preview |
/api/sessions/{id}/preview
| /api/sessions/{id}/labels | GET/POST | Get/set labels |
/api/sessions/{id}/labels
| /api/sessions/{id}/usage | GET | Get usage stats |
/api/sessions/{id}/usage
Agent skill registration and discovery.
| /api/skills | GET | List all tools (filter: ?category=, ?enabled=, ?search=) |
/api/skills
?category=
?enabled=
?search=
| /api/skills | POST | Register custom skill |
| /api/skills/categories | GET | List tool categories |
/api/skills/categories
| /api/skills/{id} | GET | Get tool details |
/api/skills/{id}
| /api/skills/{id} | PUT | Update custom skill |
| /api/skills/{id} | DELETE | Remove custom skill |
| /api/skills/{id}/toggle | POST | Toggle enabled/disabled |
/api/skills/{id}/toggle
| /api/skills/{id}/config | PUT | Set tool configuration/API keys |
/api/skills/{id}/config
CLI: aiui skills list, aiui skills status
aiui skills list
aiui skills status
Pre/post operation hooks for tool calls, agent runs, etc.
| /api/hooks | GET | List hooks |
/api/hooks
| /api/hooks | POST | Register hook |
| /api/hooks/log | GET | View execution log |
/api/hooks/log
| /api/hooks/{id} | GET | Get hook details |
/api/hooks/{id}
| /api/hooks/{id} | DELETE | Remove hook |
| /api/hooks/{id}/trigger | POST | Trigger manually |
/api/hooks/{id}/trigger
CLI: aiui hooks list, aiui hooks trigger <id>, aiui hooks log
aiui hooks list
aiui hooks trigger <id>
aiui hooks log
Multi-step workflow orchestration (Pipeline, Route, Parallel, Loop).
| /api/workflows | GET | List workflows |
/api/workflows
| /api/workflows | POST | Create workflow |
| /api/workflows/runs | GET | List all runs |
/api/workflows/runs
| /api/workflows/runs/{id} | GET | Get run details |
/api/workflows/runs/{id}
| /api/workflows/{id} | GET | Get workflow |
/api/workflows/{id}
| /api/workflows/{id} | DELETE | Delete workflow |
| /api/workflows/{id}/run | POST | Execute workflow |
/api/workflows/{id}/run
| /api/workflows/{id}/status | GET | Workflow status |
/api/workflows/{id}/status
CLI: aiui workflows list, aiui workflows run <id>, aiui workflows status, aiui workflows runs
aiui workflows list
aiui workflows run <id>
aiui workflows status
aiui workflows runs
Live runtime configuration without server restart.
| /api/config/runtime | GET | Get all config |
/api/config/runtime
| /api/config/runtime | PATCH | Merge config values |
| /api/config/runtime | PUT | Replace all config |
| /api/config/runtime/history | GET | Change history |
/api/config/runtime/history
| /api/config/runtime/{key} | GET | Get single key |
/api/config/runtime/{key}
| /api/config/runtime/{key} | PUT | Set single key |
| /api/config/runtime/{key} | DELETE | Delete key |
| /api/config/schema | GET | JSON Schema for form rendering |
/api/config/schema
| /api/config/validate | POST | Validate config without applying |
/api/config/validate
| /api/config/apply | POST | Validate and apply config |
/api/config/apply
| /api/config/defaults | GET | Get default values from schema |
/api/config/defaults
CLI: aiui config get [key], aiui config set <key> <value>, aiui config list, aiui config history
aiui config get [key]
aiui config set <key> <value>
aiui config list
aiui config history
Async job submission and monitoring with real-time SSE streaming.
| /api/jobs | GET | List jobs (filter: ?status=, ?limit=, ?offset=) |
/api/jobs
?status=
?limit=
?offset=
| /api/jobs | POST | Submit job (returns 202) |
| /api/jobs/stats | GET | Executor statistics |
/api/jobs/stats
| /api/jobs/{id} | GET | Get job details |
/api/jobs/{id}
| /api/jobs/{id} | DELETE | Delete completed job |
| /api/jobs/{id}/status | GET | Get status + progress |
/api/jobs/{id}/status
| /api/jobs/{id}/result | GET | Get result (409 if not complete) |
/api/jobs/{id}/result
| /api/jobs/{id}/cancel | POST | Cancel running job |
/api/jobs/{id}/cancel
| /api/jobs/{id}/stream | GET | SSE stream (status/progress/result/error events) |
/api/jobs/{id}/stream
CLI: aiui job list, aiui job status [id], aiui job stats
aiui job list
aiui job status [id]
aiui job stats
Usage analytics with per-model cost tracking, time-series data, and breakdowns.
| /api/usage | GET | Summary (totals, averages) |
/api/usage
| /api/usage/details | GET | Detailed usage records |
/api/usage/details
| /api/usage/models | GET | Per-model breakdown |
/api/usage/models
| /api/usage/sessions | GET | Per-session breakdown |
/api/usage/sessions
| /api/usage/agents | GET | Per-agent breakdown |
/api/usage/agents
| /api/usage/timeseries | GET | Time-series data for charts |
/api/usage/timeseries
| /api/usage/costs | GET | Cost table (21 models) |
/api/usage/costs
| /api/usage/track | POST | Track usage event |
/api/usage/track
CLI: aiui usage summary, aiui usage models, aiui usage cost
aiui usage summary
aiui usage models
aiui usage cost
Agent definition CRUD with model selection, execution via praisonaiagents.Agent.
praisonaiagents.Agent
| /api/agents/definitions | GET | List all agent definitions |
/api/agents/definitions
| /api/agents/definitions | POST | Create new agent |
| /api/agents/definitions/{id} | GET | Get agent details |
/api/agents/definitions/{id}
| /api/agents/definitions/{id} | PUT | Update agent |
| /api/agents/definitions/{id} | DELETE | Delete agent |
| /api/agents/models | GET | List available models (13 models) |
/api/agents/models
| /api/agents/duplicate/{id} | POST | Duplicate an agent |
/api/agents/duplicate/{id}
| /api/agents/run/{id} | POST | Execute agent via Agent.start() |
/api/agents/run/{id}
Agent.start()
CLI: aiui agents list, aiui agents create
aiui agents list
aiui agents create
OpenAI-compatible /v1/* API routes wrapping praisonai.capabilities.
/v1/*
praisonai.capabilities
| /v1 | GET | API info / endpoint list |
/v1
| /v1/chat/completions | POST | Chat completions |
/v1/chat/completions
| /v1/completions | POST | Legacy text completions |
/v1/completions
| /v1/embeddings | POST | Create embeddings |
/v1/embeddings
| /v1/images/generations | POST | Generate images |
/v1/images/generations
| /v1/audio/transcriptions | POST | Transcribe audio |
/v1/audio/transcriptions
| /v1/audio/speech | POST | Text to speech |
/v1/audio/speech
| /v1/moderations | POST | Content moderation |
/v1/moderations
| /v1/models | GET | List available models |
/v1/models
| /v1/models/{id} | GET | Get model info |
/v1/models/{id}
| /v1/responses | POST | OpenAI Responses API |
/v1/responses
| /v1/files | GET/POST | File management |
/v1/files
| /v1/files/{id} | GET/DELETE | File operations |
/v1/files/{id}
| /v1/assistants | GET/POST | Assistants API |
/v1/assistants
Real-time log streaming via WebSocket with level filtering.
| /api/logs/stream | WS | WebSocket for real-time log streaming |
/api/logs/stream
| /api/logs/levels | GET | Available log levels with colors |
/api/logs/levels
| /api/logs/stats | GET | Log buffer statistics |
/api/logs/stats
| /api/logs/clear | POST | Clear log buffer |
/api/logs/clear
CLI: aiui logs tail, aiui logs clear
aiui logs tail
aiui logs clear
Multi-mode authentication (none, api_key, session, password).
| /api/auth/status | GET | Current auth status |
/api/auth/status
| /api/auth/config | GET | Get auth config |
/api/auth/config
| /api/auth/config | PUT | Set auth config |
| /api/auth/keys | GET | List API keys |
/api/auth/keys
| /api/auth/keys | POST | Create API key |
| /api/auth/keys/{id} | DELETE | Revoke API key |
/api/auth/keys/{id}
| /api/auth/login | POST | Login with password |
/api/auth/login
| /api/auth/logout | POST | Logout session |
/api/auth/logout
| /api/auth/sessions | GET | List active sessions |
/api/auth/sessions
| /api/auth/password | POST | Set/change password |
/api/auth/password
> Important: When defining routes with parametric paths (e.g., /{id}), always place literal paths (e.g., /log, /runs) before the parametric route. Starlette matches routes in order, and a parametric route will capture literal segments as parameter values.
/{id}
/log
/runs