Reference
API Reference Complete REST API reference for the Talome backend.
Talome's backend is a Hono server running on port 4000 (configurable via CORE_PORT). It exposes a REST API that the dashboard, MCP server, and external clients use to interact with the system. The API currently spans 47 route files covering every aspect of the platform.
All API routes except /api/health and the initial setup endpoint require a valid JWT session token. The token can be provided in two ways:
Cookie : the talome_session cookie, set automatically on loginBearer header : Authorization: Bearer <token>
Tokens are signed with TALOME_SECRET (a 64-character hex string). Sessions can be revoked server-side.
# Example: authenticate and use the token TOKEN = $( curl -s -X POST http://localhost:4000/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"your-password"}' \ | jq -r '.token' ) curl http://localhost:4000/api/containers \ -H "Authorization: Bearer $TOKEN " Method Path Description POST /api/auth/loginAuthenticate with username and password. On first call with no existing users, creates the admin account. Returns JWT token. POST /api/auth/logoutRevoke the current session and clear the session cookie. POST /api/auth/recoverReset password using a recovery code. Requires username, recoveryCode, and newPassword. GET /api/auth/meGet the currently authenticated user's profile. GET /api/healthHealth check endpoint (no auth required). Returns { status: "ok" }.
Method Path Description GET /api/containersList all Docker containers with status, image, ports, and resource usage. GET /api/containers/:idGet detailed information about a specific container. POST /api/containers/:id/startStart a stopped container. POST /api/containers/:id/stopStop a running container. POST /api/containers/:id/restartRestart a container. GET /api/containers/:id/logsGet container logs. Query params: tail (number of lines), since (timestamp). GET /api/containers/:id/statsGet live CPU, memory, and network stats for a container. POST /api/containers/:id/execExecute a command inside a container. Body: { command: string }. GET /api/containers/:id/inspectFull Docker inspect output for a container.
Method Path Description GET /api/appsList all available apps across all store sources. Query params: category, search, source. GET /api/apps/:idGet detailed app manifest including compose configuration. POST /api/apps/installInstall an app. Body: { appId, storeId, env?, ports? }. DELETE /api/apps/:idUninstall an app and remove its containers. POST /api/apps/:id/startStart all containers for an installed app. POST /api/apps/:id/stopStop all containers for an installed app. POST /api/apps/:id/restartRestart all containers for an installed app. POST /api/apps/:id/updateUpdate an app to its latest version. GET /api/apps/updatesCheck for available updates across all installed apps. POST /api/apps/bulkBulk action on multiple apps. Body: { action, appIds }.
Method Path Description GET /api/storesList all configured store sources with app counts. POST /api/storesAdd a new store source. Body: { name, type, gitUrl?, branch? }. POST /api/stores/:id/syncTrigger a sync for a specific store source. DELETE /api/stores/:idRemove a store source.
Method Path Description GET /api/user-appsList user-created apps ("Your Creations"). POST /api/user-appsCreate or update a user app manifest. DELETE /api/user-apps/:idDelete a user-created app.
Method Path Description POST /api/chatStream an AI chat response. Body: { messages, conversationId? }. Returns Server-Sent Events with the Vercel AI SDK streaming protocol. GET /api/conversationsList all conversations with pagination. Query params: limit, offset. GET /api/conversations/:idGet a conversation with all its messages. DELETE /api/conversations/:idDelete a conversation and its messages. GET /api/suggestionsGet AI-generated improvement suggestions for the system.
Method Path Description GET /api/settingsGet all settings as key-value pairs. PUT /api/settingsUpdate one or more settings. Body: { key: value, ... }. GET /api/settings/historyGet settings change history.
These endpoints power the dashboard's media browsing, streaming, and optimization features.
Method Path Description GET /api/media/libraryGet media library contents with filtering and pagination. GET /api/media/searchSearch for movies and TV shows. GET /api/media/downloadsGet active downloads with progress. GET /api/media/calendarGet upcoming and recent releases. POST /api/media/requestRequest a movie or TV show for download. GET /api/media/stream/:idStream a media file (HLS or direct). GET /api/media/stream/:id/manifest.m3u8Get HLS manifest for transcoded playback. GET /api/media/stream/:id/segment/:segGet an HLS segment. GET /api/media/subtitles/:idGet subtitle tracks for a media item. GET /api/media/metadata/:idGet full metadata for a media item.
Method Path Description GET /api/automationsList all automations. POST /api/automationsCreate a new automation. PUT /api/automations/:idUpdate an automation. DELETE /api/automations/:idDelete an automation. GET /api/automations/:id/runsGet execution history for an automation. POST /api/automations/:id/runManually trigger an automation.
Method Path Description GET /api/notificationsList recent notifications. Query params: unread, limit. PUT /api/notifications/:id/readMark a notification as read. PUT /api/notifications/read-allMark all notifications as read. GET /api/notification-channelsList configured notification channels. POST /api/notification-channelsAdd a notification channel. DELETE /api/notification-channels/:idRemove a notification channel. POST /api/notification-channels/:id/testSend a test notification.
Method Path Description GET /api/filesBrowse directory contents. Query params: path, sort. GET /api/files/infoGet file metadata. Query params: path. POST /api/files/mkdirCreate a directory. Body: { path }. POST /api/files/renameRename or move a file. Body: { from, to }. DELETE /api/filesDelete a file. Query params: path. GET /api/files/downloadDownload a file. Query params: path. POST /api/files/uploadUpload a file. Multipart form data with file and path fields.
Method Path Description POST /api/backups/:appIdCreate a backup for an app. POST /api/backups/:appId/restoreRestore an app from a backup. GET /api/backups/:appId/listList available backups for an app.
Method Path Description GET /api/proxy/routesList all proxy routes. POST /api/proxy/routesAdd a proxy route. Body: { domain, upstream, tlsMode? }. DELETE /api/proxy/routes/:idRemove a proxy route. POST /api/proxy/reloadReload the Caddy proxy configuration.
Method Path Description GET /api/networksList Docker networks. POST /api/networksCreate a Docker network. Body: { name, driver? }. DELETE /api/networks/:idRemove a Docker network.
Method Path Description GET /api/widgetsList all dashboard widgets. POST /api/widgetsCreate or update a widget manifest. PUT /api/widgets/:idUpdate a widget. DELETE /api/widgets/:idDelete a widget.
Method Path Description GET /api/system/statsCurrent CPU, memory, disk, and network stats. GET /api/system/healthOverall system health assessment. GET /api/system/gpuGPU status and utilization. GET /api/metricsHistorical metrics data. Query params: period (1h, 6h, 24h, 7d). GET /api/stats-streamServer-Sent Events stream of real-time system stats.
Method Path Description GET /api/optimization/statusGet optimization queue status. POST /api/optimization/queueQueue a file for optimization. DELETE /api/optimization/:idCancel an optimization job. GET /api/optimization/configGet optimization configuration. PUT /api/optimization/configUpdate optimization configuration.
Method Path Description GET /api/terminal/sessionsList active terminal sessions. POST /api/terminal/sessionsCreate a new terminal session. DELETE /api/terminal/sessions/:idClose a terminal session.
The terminal uses WebSocket connections on port 4001 (configurable via TERMINAL_DAEMON_PORT) for real-time PTY communication.
Method Path Description GET /api/evolution/runsList self-improvement runs. GET /api/evolution/runs/:idGet details of a specific run. POST /api/evolution/runsStart a new self-improvement run. DELETE /api/evolution/runs/:idCancel a running evolution task. GET /api/evolution/suggestionsList AI-generated improvement suggestions. POST /api/evolution/suggestions/:id/approveApprove and execute a suggestion. POST /api/evolution/suggestions/:id/dismissDismiss a suggestion.
Method Path Description POST /mcpMCP protocol endpoint for stdio-based tool execution. Used by Claude Code, Cursor, and other MCP clients.
Method Path Description GET /api/usersList all users (admin only). POST /api/usersCreate a new user (admin only). PUT /api/users/:idUpdate a user's role or permissions (admin only). DELETE /api/users/:idDelete a user (admin only).
Method Path Description POST /api/webhooks/:idReceive a webhook trigger for an automation. The :id is the automation's webhook token.
Route File Description /api/storageStorage breakdown, SMART status, and reclaimable space analysis. /api/searchCross-system search across apps, containers, files, and media. /api/integrationsIntegration configuration and status for Sonarr, Radarr, etc. /api/audiobooksAudiobookshelf library browsing, search, and progress tracking. /api/servicesService discovery and health monitoring. /api/stacksFeature stack management (curated app bundles). /api/ai-modelsList available AI models and providers. /api/audit-logQuery the audit log with filtering. /api/memoriesCRUD operations on AI memories. /api/mdnsmDNS/CoreDNS management. /api/ollamaOllama model management proxy. /api/pushWeb push notification subscription. /api/communityCommunity app submission and review. /api/toolsList available AI tools and their metadata. /api/supervisorAgent loop and autonomous remediation management.
All error responses follow a consistent format:
{ "error" : "Human-readable error message" } Common HTTP status codes:
Code Meaning 400 Invalid request body or parameters (Zod validation failure) 401 Missing or invalid authentication token 403 Insufficient permissions for the requested action 404 Resource not found 500 Internal server error
The API does not currently enforce rate limits. The AI chat endpoint uses Vercel AI SDK streaming, which is subject to the upstream LLM provider's rate limits.