Server Interact with atlas server over HTTP.
The atlas serve command runs a headless HTTP server that exposes an OpenAPI endpoint that an atlas client can use.
atlas serve [--port < numbe r > ] [--hostname < strin g > ] [--cors < origi n > ] Flag Description Default --portPort to listen on 4096--hostnameHostname to listen on 127.0.0.1--mdnsEnable mDNS discovery false--mdns-domainCustom domain name for mDNS service atlas.local--corsAdditional browser origins to allow []
--cors can be passed multiple times:
atlas serve --cors http://localhost:5173 --cors https://app.example.com Set ATLAS_SERVER_PASSWORD to protect the server with HTTP basic auth. The username defaults to atlas, or set ATLAS_SERVER_USERNAME to override it. This applies to both atlas serve and atlas web.
ATLAS_SERVER_PASSWORD = your-password atlas serve When you run atlas it starts a TUI and a server. Where the TUI is the
client that talks to the server. The server exposes an OpenAPI 3.1 spec
endpoint. This endpoint is also used to generate an SDK .
Use the atlas server to interact with atlas programmatically.
This architecture lets atlas support multiple clients and allows you to interact with atlas programmatically.
You can run atlas serve to start a standalone server. If you have the
atlas TUI running, atlas serve will start a new server.
When you start the TUI it randomly assigns a port and hostname. You can instead pass in the --hostname and --port flags . Then use this to connect to its server.
The /tuiIDE plugins.
The server publishes an OpenAPI 3.1 spec that can be viewed at:
http://<hostname>:<port>/doc For example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
The atlas server exposes the following APIs.
Method Path Description Response GET/global/healthGet server health and version { healthy: true, version: string }GET/global/eventGet global events (SSE stream) Event stream
Method Path Description Response GET/projectList all projects Project[]GET/project/currentGet the current project Project
Method Path Description Response GET/pathGet the current path PathGET/vcsGet VCS info for the current project VcsInfo
Method Path Description Response POST/instance/disposeDispose the current instance boolean
Method Path Description Response GET/configGet config info ConfigPATCH/configUpdate config ConfigGET/config/providersList providers and default models { providers: Provider[] , default: { [key: string]: string } }
Method Path Description Response GET/providerList all providers { all: Provider[] , default: {...}, connected: string[] }GET/provider/authGet provider authentication methods { [providerID: string]: ProviderAuthMethod[] }POST/provider/{id}/oauth/authorizeAuthorize a provider using OAuth ProviderAuthAuthorizationPOST/provider/{id}/oauth/callbackHandle OAuth callback for a provider boolean
Method Path Description Notes GET/sessionList all sessions Returns Session[] POST/sessionCreate a new session body: { parentID?, title? }, returns Session GET/session/statusGet session status for all sessions Returns { [sessionID: string]: SessionStatus } GET/session/:idGet session details Returns Session DELETE/session/:idDelete a session and all its data Returns boolean PATCH/session/:idUpdate session properties body: { title? }, returns Session GET/session/:id/childrenGet a session's child sessions Returns Session[] GET/session/:id/todoGet the todo list for a session Returns Todo[] POST/session/:id/initAnalyze app and create AGENTS.md body: { messageID, providerID, modelID }, returns boolean POST/session/:id/forkFork an existing session at a message body: { messageID? }, returns Session POST/session/:id/abortAbort a running session Returns boolean POST/session/:id/shareShare a session Returns Session DELETE/session/:id/shareUnshare a session Returns Session GET/session/:id/diffGet the diff for this session query: messageID?, returns FileDiff[] POST/session/:id/summarizeSummarize the session body: { providerID, modelID }, returns boolean POST/session/:id/revertRevert a message body: { messageID, partID? }, returns boolean POST/session/:id/unrevertRestore all reverted messages Returns boolean POST/session/:id/permissions/:permissionIDRespond to a permission request body: { response, remember? }, returns boolean
Method Path Description Notes GET/session/:id/messageList messages in a session query: limit?, returns { info: Message , parts: Part[] }[] POST/session/:id/messageSend a message and wait for response body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, returns { info: Message , parts: Part[] } GET/session/:id/message/:messageIDGet message details Returns { info: Message , parts: Part[] } POST/session/:id/prompt_asyncSend a message asynchronously (no wait) body: same as /session/:id/message, returns 204 No Content POST/session/:id/commandExecute a slash command body: { messageID?, agent?, model?, command, arguments }, returns { info: Message , parts: Part[] } POST/session/:id/shellRun a shell command body: { agent, model?, command }, returns { info: Message , parts: Part[] }
Method Path Description Response GET/commandList all commands Command[]
Method Path Description Response GET/find?pattern=<pat>Search for text in files Array of match objects with path, lines, line_number, absolute_offset, submatches GET/find/file?query=<q>Find files and directories by name string[] (paths)GET/find/symbol?query=<q>Find workspace symbols Symbol[]GET/file?path=<path>List files and directories FileNode[]GET/file/content?path=<p>Read a file FileContentGET/file/statusGet status for tracked files File[]
query (required) — search string (fuzzy match)type (optional) — limit results to "file" or "directory"directory (optional) — override the project root for the searchlimit (optional) — max results (1–200)dirs (optional) — legacy flag ("false" returns only files)
Method Path Description Response GET/experimental/tool/idsList all tool IDs ToolIDsGET/experimental/tool?provider=<p>&model=<m>List tools with JSON schemas for a model ToolList
Method Path Description Response GET/lspGet LSP server status LSPStatus[]GET/formatterGet formatter status FormatterStatus[]GET/mcpGet MCP server status { [name: string]: MCPStatus }POST/mcpAdd MCP server dynamically body: { name, config }, returns MCP status object
Method Path Description Response GET/agentList all available agents Agent[]
Method Path Description Response POST/logWrite log entry. Body: { service, level, message, extra? } boolean
Method Path Description Response POST/tui/append-promptAppend text to the prompt booleanPOST/tui/open-helpOpen the help dialog booleanPOST/tui/open-sessionsOpen the session selector booleanPOST/tui/open-themesOpen the theme selector booleanPOST/tui/open-modelsOpen the model selector booleanPOST/tui/submit-promptSubmit the current prompt booleanPOST/tui/clear-promptClear the prompt booleanPOST/tui/execute-commandExecute a command ({ command }) booleanPOST/tui/show-toastShow toast ({ title?, message, variant }) booleanGET/tui/control/nextWait for the next control request Control request object POST/tui/control/responseRespond to a control request ({ body }) boolean
Method Path Description Response PUT/auth/:idSet authentication credentials. Body must match provider schema boolean
Method Path Description Response GET/eventServer-sent events stream. First event is server.connected, then bus events Server-sent events stream
Method Path Description Response GET/docOpenAPI 3.1 specification HTML page with OpenAPI spec