API Reference
Complete REST API for managing conversations, plans, jobs, and integrations.
Base URL is https://localhost:5173/api (port configurable via the TALKIE_PORT environment variable). All responses are JSON unless otherwise noted. SSE endpoints return text/event-stream.
curl or other HTTP clients, you will need to pass the --insecure flag (or equivalent) to skip certificate verification.
Status & Health
Health check. Returns the current avatar state, active conversation ID, and database connection status.
Returns the status of MCP server and Telegram bot integrations, including whether each is connected and active.
Conversations
List all conversations. Supports limit and offset query parameters for pagination.
Create a new conversation. Body: { "title": "string" }
Get a single conversation with all its messages and activities included.
Update a conversation. Body: { "title": "string", "parent_id": "string", "project_id": "string" }
Delete a conversation and all its associated messages, activities, and images.
Get the liner notes text for a conversation.
Save liner notes for a conversation. Body: { "notes": "string" }
Add a message to a conversation. Body: { "role": "user|assistant", "content": "string", "images": [], "activities": [] }
Update the description of an attached image. Body: { "description": "string" }
Plans
List all plans. Supports status and conversation_id query parameters for filtering.
Get a single plan by ID.
Create a new plan. Body: { "title": "string", "content": "string", "status": "draft|approved|in_progress|completed|archived", "conversation_id": "string" }
Update an existing plan. Body: { "title": "string", "content": "string", "status": "draft|approved|in_progress|completed|archived" }
Delete a plan by ID.
Jobs
List all jobs. Supports status query parameter for filtering (queued, running, completed, failed, cancelled).
Create a new background job. Body: { "conversation_id": "string", "prompt": "string" }
Get the status and result of a job by ID.
SSE stream for real-time job events. Returns text/event-stream with JSON-encoded events as the job progresses.
Cancel a running job by ID.
Search
Full-text search across all conversations. Query parameters: q (search query, required), limit (max results). Returns snippets with highlighted matches.
IPC
The IPC (Inter-Process Communication) endpoints enable communication between the Talkie frontend and external tools like the MCP server. The frontend posts messages, and MCP tools poll for pending messages and respond.
Check for a pending message from the frontend. Returns the message content if one is waiting, or an empty response if not.
Send an IPC response back to the frontend. Body: { "content": "string" }
Send a message and wait for a response via SSE. Body: { "content": "string", "conversation_id": "string" }. Returns a text/event-stream with the response.
Sessions
Get the currently connected Claude Code session ID.
Set the Claude Code session ID to connect Talkie to a running session. Body: { "sessionId": "string" }
Clear the connected Claude Code session.
Claude Code
Spawn a fresh claude -p CLI process and stream the response as SSE. Body: { "prompt": "string", "conversation_id": "string", "images": [] }. Returns a stream of JSON events with types: assistant (text chunks), activity (tool usage), result (final response), and error.
/api/claude-code spawns a fresh CLI process with the flags --no-session-persistence and --permission-mode bypassPermissions. There is no persistent session between requests.
Media
Analyze an image using Claude vision via the Anthropic API key. Body: image data URL (base64-encoded).
Analyze an image using Claude vision via the Claude Code CLI. Same input format as the API key variant, but routes through the CLI.
Open a URL in the default system browser. Body: { "url": "string" }
Migration
Import conversations from localStorage format into the SQLite database. Used for migrating data from older versions of Talkie that stored conversations in the browser.
Examples
Create a new conversation using curl:
curl -X POST https://localhost:5173/api/conversations \
-H "Content-Type: application/json" \
-d '{"title": "My First Tape"}' \
--insecureThe --insecure flag is needed because Talkie uses self-signed certificates. In production HTTP clients, you would configure the CA certificate or disable verification as appropriate for your environment.
List all conversations with pagination:
curl https://localhost:5173/api/conversations?limit=10&offset=0 \
--insecureSearch across all messages:
curl "https://localhost:5173/api/search?q=cassette&limit=5" \
--insecureCreate a background job:
curl -X POST https://localhost:5173/api/jobs \
-H "Content-Type: application/json" \
-d '{"conversation_id": "abc-123", "prompt": "Summarize this conversation"}' \
--insecureStream Claude Code output with SSE:
curl -N -X POST https://localhost:5173/api/claude-code \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello, Claude!", "conversation_id": "abc-123"}' \
--insecure-N flag with curl to disable output buffering when streaming SSE endpoints. This ensures events are printed as they arrive.