Skip to content

Interfaces

Jump to bottom
Francesco Caracciolo edited this page May 13, 2026 · 3 revisions

Interfaces are services that allow third party applications to interact with Newelle. Interfaces can be added by Newelle Extensions and can be used to connect external services (like messaging apps), provide alternative UIs, use Newelle remotely or integrate it somewhere else.

If you want to create a custom interface, read Creating Interfaces.

Available Interfaces

By default, Newelle provides these interfaces:

OpenAI Compatible API (api)

Exposes the current LLM as an OpenAI-compatible API server. Supports LLM chat completions, TTS, STT, and embeddings.

Endpoints:

Method Path Description
POST /v1/chat/completions Standard OpenAI-compatible chat completions
POST /v2/chat/completions Agent endpoint with tools, commands, and per-user persistent chat
GET /v1/models List available models
POST /v1/audio/speech Text-to-Speech (streaming supported if TTS handler supports it)
POST /v1/audio/transcriptions Speech-to-Text transcription
POST /v1/embeddings Text embeddings

v2 differences: The /v2/chat/completions endpoint runs the full Newelle agent with tools, commands, and per-user persistent chat (chat history is maintained across requests for the same user).

Authentication: Set an API key in settings; requests need Authorization: Bearer <key> header or ?api_key=<key> query parameter.

Newelle GUI API (gui-api)

Full REST API for building alternative UIs or integrating deeply with Newelle. Allows programmatic control over chats, messages, profiles, tools, prompts, folders, interfaces, LLM settings, TTS/STT, and more.

Key features:

  • CRUD operations on chats, messages, folders, profiles
  • LLM execution with tool support
  • SSE streaming for real-time chat generation with tool interaction
  • Tool management (enable/disable, MCP tools)
  • Prompt management
  • TTS/STT endpoints
  • OpenAI-compatible /v1/chat/completions and /v1/models endpoints
  • Interface lifecycle control (start/stop)
  • Settings import/export

Telegram Bot (telegram)

Chat with Newelle via Telegram. Features:

  • Text messaging with streaming responses (via message drafts or edit-in-place)
  • Voice message transcription via STT
  • Photo/image analysis via vision-capable LLMs
  • Inline keyboard buttons for tool interactions
  • Full set of built-in slash commands

Built-in Telegram commands:

Command Description
/start Welcome message with available commands
/new [name] Create a new chat for this user
/models List available LLM providers and models
/model [provider:]model Switch the current model
/profile <name> Switch to a different profile
/prompts View available prompts and their status
/tools [toggle <name>] List or toggle tools
/scheduled View scheduled tasks
/skill <name> Execute a skill command
/cd [path] Change working directory
/list_chats List all chats
/peek <chat_id> Preview messages from a chat
/resume <chat_id> Switch to a different chat
/autoexec Toggle auto command execution
/option <n> Choose a pending tool interaction option

Starting an interface

Interfaces can be started via GUI or Terminal.

Starting an interface via GUI

TODO

Starting an interface via Terminal

Warning

The following commands will consider Newelle installed as a package. If you installed Newelle as a flatpak, run flatpak run io.github.qwersyk.Newelle instead of newelle

  • Listing the available interfaces
newelle --interfaces
  • Running an interface in headless mode
newelle --interface interface

For example, to start the telegram interface without the gui,

newelle --interface telegram

Clone this wiki locally