API Reference HTTP and WebSocket API for programmatic access to Pi Session Manager.
Pi Session Manager exposes its full functionality through HTTP and WebSocket APIs. Both protocols share the same command router (dispatch()), so every command works identically on both.
POST http://127.0.0.1:52131/api Content-Type: application/json { "command" : "command_name" , "payload" : { } } { "success" : true , "data" : { }, "error" : null } When accessing from a non-localhost address, requests must include a Bearer token:
curl -X POST http://your-server:52131/api \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{"command":"scan_sessions","payload":{}}' Tokens can also be passed as a query parameter: ?token=YOUR_API_TOKEN
Manage tokens via the API itself or through Settings → Advanced → API Keys.
Send JSON messages in the same { command, payload } format. Responses are pushed back on the same connection.
After connecting, send an auth message if required:
{ "command" : "auth" , "payload" : { "token" : "YOUR_API_TOKEN" }} The WebSocket connection also receives push events:
session-changed — when session files are modified (includes changed_paths for incremental rescan)sessions-diff — incremental session list updates
For HTTP-only clients that need real-time updates:
GET http://127.0.0.1:52131/api/events Streams the same events as WebSocket in SSE format. Used by the mobile web frontend as a WebSocket alternative.
Command Payload Description scan_sessions{}Scan and return all sessions read_session_file{ "path": "..." }Read a session's JSONL content rename_session{ "path": "...", "name": "..." }Rename a session delete_session{ "path": "..." }Move a session file to Trash/Recycling Bin when available, fall back to permanent delete only if recoverable delete is unavailable, and clean up cache records export_session{ "path": "...", "format": "html|markdown|json" }Export a session
Command Payload Description search{ "query": "...", "role": "all|user|assistant|tool" }Full-text search
Command Payload Description list_tags{}List all tags create_tag{ "name": "...", "color": "...", "parent_id": null }Create a tag update_tag{ "id": ..., "name": "...", "color": "..." }Update a tag delete_tag{ "id": ... }Delete a tag assign_tag{ "session_path": "...", "tag_id": ... }Assign tag to session remove_tag{ "session_path": "...", "tag_id": ... }Remove tag from session
Command Payload Description list_favorites{}List favorited session paths toggle_favorite{ "path": "..." }Toggle favorite status
Command Payload Description get_session_paths{}Get configured session directories save_session_paths{ "paths": ["..."] }Update session directories get_all_session_dirs{}Get all resolved scan directories get_config_bundle{}Get full config bundle save_config_bundle{ ... }Save config bundle list_config_versions{}List config version history
Command Payload Description list_tokens{}List API tokens create_token{ "name": "..." }Create a new API token revoke_token{ "id": ... }Revoke an API token
Command Payload Description get_session_stats{}Get aggregated session statistics
Command Payload Description load_model_config{}Load current model config save_model_config{ ... }Save model config import_model_config_from_path{ "path": "..." }Import model config from file export_model_config_to_path{ "path": "..." }Export model config to file list_model_config_backups{}List model config backups restore_model_config_backup{ "backup_name": "..." }Restore a backup
Command Payload Description list_skills{}List Pi skills list_prompts{}List Pi prompts list_themes{}List Pi themes
Command Payload Description get_pi_live_sessions{}List active Pi CLI sessions get_pi_agent_entries{ "session_id": "..." }Fetch cached history for live session send_pi_agent_rpc{ "session_id": "...", "prompt": "..." }Send prompt to Pi CLI
Command Payload Description create_terminal{ "cwd": "..." }Create new PTY session terminal_write{ "id": "...", "data": "..." }Write to PTY terminal_resize{ "id": "...", "cols": N, "rows": N }Resize terminal terminal_close{ "id": "..." }Close PTY session
Command Payload Description ping{}Health check (returns { "pong": true })
curl -s -X POST http://127.0.0.1:52131/api \ -H "Content-Type: application/json" \ -d '{"command":"scan_sessions","payload":{}}' | jq '.data | length' curl -s -X POST http://127.0.0.1:52131/api \ -H "Content-Type: application/json" \ -d '{"command":"search","payload":{"query":"authentication bug","role":"all"}}' | jq wscat -c ws://127.0.0.1:52131/ws > { "command" : "scan_sessions" , "payload" : {} } < { "success" :true, "data" : [ ... ]}
The HTTP endpoint also supports GET /health which returns 200 OK — useful for load balancer health checks and monitoring.