feat: External API Endpoints

python/api/api_files_get.py

@@ -0,0 +1,95 @@
+import base64
+import os
+from python.helpers.api import ApiHandler, Request, Response
+from python.helpers import files
+from python.helpers.print_style import PrintStyle
+import json
+
+
+class ApiFilesGet(ApiHandler):
+    @classmethod
+    def requires_auth(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_csrf(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_api_key(cls) -> bool:
+        return True
+
+    @classmethod
+    def get_methods(cls) -> list[str]:
+        return ["POST"]
+
+    async def process(self, input: dict, request: Request) -> dict | Response:
+        try:
+            # Get paths from input
+            paths = input.get("paths", [])
+
+            if not paths:
+                return Response(
+                    '{"error": "paths array is required"}',
+                    status=400,
+                    mimetype="application/json"
+                )
+
+            if not isinstance(paths, list):
+                return Response(
+                    '{"error": "paths must be an array"}',
+                    status=400,
+                    mimetype="application/json"
+                )
+
+            result = {}
+
+            for path in paths:
+                try:
+                    # Convert internal paths to external paths
+                    if path.startswith("/a0/tmp/uploads/"):
+                        # Internal path - convert to external
+                        filename = path.replace("/a0/tmp/uploads/", "")
+                        external_path = files.get_abs_path("tmp/uploads", filename)
+                        filename = os.path.basename(external_path)
+                    elif path.startswith("/a0/"):
+                        # Other internal Agent Zero paths
+                        relative_path = path.replace("/a0/", "")
+                        external_path = files.get_abs_path(relative_path)
+                        filename = os.path.basename(external_path)
+                    else:
+                        # Assume it's already an external/absolute path
+                        external_path = path
+                        filename = os.path.basename(path)
+
+                    # Check if file exists
+                    if not os.path.exists(external_path):
+                        PrintStyle.warning(f"File not found: {path}")
+                        continue
+
+                    # Read and encode file
+                    with open(external_path, "rb") as f:
+                        file_content = f.read()
+                        base64_content = base64.b64encode(file_content).decode('utf-8')
+                        result[filename] = base64_content
+
+                    PrintStyle().print(f"Retrieved file: {filename} ({len(file_content)} bytes)")
+
+                except Exception as e:
+                    PrintStyle.error(f"Failed to read file {path}: {str(e)}")
+                    continue
+
+            # Log the retrieval
+            PrintStyle(
+                background_color="#2ECC71", font_color="white", bold=True, padding=True
+            ).print(f"API Files retrieved: {len(result)} files")
+
+            return result
+
+        except Exception as e:
+            PrintStyle.error(f"API files get error: {str(e)}")
+            return Response(
+                json.dumps({"error": f"Internal server error: {str(e)}"}),
+                status=500,
+                mimetype="application/json"
+            )

python/api/api_log_get.py

@@ -0,0 +1,64 @@
+from agent import AgentContext
+from python.helpers.api import ApiHandler, Request, Response
+
+
+class ApiLogGet(ApiHandler):
+    @classmethod
+    def get_methods(cls) -> list[str]:
+        return ["GET", "POST"]
+
+    @classmethod
+    def requires_auth(cls) -> bool:
+        return False  # No web auth required
+
+    @classmethod
+    def requires_csrf(cls) -> bool:
+        return False  # No CSRF required
+
+    @classmethod
+    def requires_api_key(cls) -> bool:
+        return True  # Require API key
+
+    async def process(self, input: dict, request: Request) -> dict | Response:
+        # Extract parameters (support both query params for GET and body for POST)
+        if request.method == "GET":
+            context_id = request.args.get("context_id", "")
+            length = int(request.args.get("length", 100))
+        else:
+            context_id = input.get("context_id", "")
+            length = input.get("length", 100)
+
+        if not context_id:
+            return Response('{"error": "context_id is required"}', status=400, mimetype="application/json")
+
+        # Get context
+        context = AgentContext.get(context_id)
+        if not context:
+            return Response('{"error": "Context not found"}', status=404, mimetype="application/json")
+
+        try:
+            # Get total number of log items
+            total_items = len(context.log.logs)
+
+            # Calculate start position (from newest, so we work backwards)
+            start_pos = max(0, total_items - length)
+
+            # Get log items from the calculated start position
+            log_items = context.log.output(start=start_pos)
+
+            # Return log data with metadata
+            return {
+                "context_id": context_id,
+                "log": {
+                    "guid": context.log.guid,
+                    "total_items": total_items,
+                    "returned_items": len(log_items),
+                    "start_position": start_pos,
+                    "progress": context.log.progress,
+                    "progress_active": context.log.progress_active,
+                    "items": log_items
+                }
+            }
+
+        except Exception as e:
+            return Response(f'{{"error": "{str(e)}"}}', status=500, mimetype="application/json")

python/api/api_message.py

@@ -0,0 +1,140 @@
+import base64
+import os
+from datetime import datetime, timedelta
+from agent import AgentContext, UserMessage, AgentContextType
+from python.helpers.api import ApiHandler, Request, Response
+from python.helpers import files
+from python.helpers.print_style import PrintStyle
+from werkzeug.utils import secure_filename
+from initialize import initialize_agent
+import threading
+
+
+class ApiMessage(ApiHandler):
+    # Track chat lifetimes for cleanup
+    _chat_lifetimes = {}
+    _cleanup_lock = threading.Lock()
+
+    @classmethod
+    def requires_auth(cls) -> bool:
+        return False  # No web auth required
+
+    @classmethod
+    def requires_csrf(cls) -> bool:
+        return False  # No CSRF required
+
+    @classmethod
+    def requires_api_key(cls) -> bool:
+        return True  # Require API key
+
+    async def process(self, input: dict, request: Request) -> dict | Response:
+        # Extract parameters
+        context_id = input.get("context_id", "")
+        message = input.get("message", "")
+        attachments = input.get("attachments", [])
+        lifetime_hours = input.get("lifetime_hours", 24)  # Default 24 hours
+
+        if not message:
+            return Response('{"error": "Message is required"}', status=400, mimetype="application/json")
+
+        # Handle attachments (base64 encoded)
+        attachment_paths = []
+        if attachments:
+            upload_folder_int = "/a0/tmp/uploads"
+            upload_folder_ext = files.get_abs_path("tmp/uploads")
+            os.makedirs(upload_folder_ext, exist_ok=True)
+
+            for attachment in attachments:
+                if not isinstance(attachment, dict) or "filename" not in attachment or "base64" not in attachment:
+                    continue
+
+                try:
+                    filename = secure_filename(attachment["filename"])
+                    if not filename:
+                        continue
+
+                    # Decode base64 content
+                    file_content = base64.b64decode(attachment["base64"])
+
+                    # Save to temp file
+                    save_path = os.path.join(upload_folder_ext, filename)
+                    with open(save_path, "wb") as f:
+                        f.write(file_content)
+
+                    attachment_paths.append(os.path.join(upload_folder_int, filename))
+                except Exception as e:
+                    PrintStyle.error(f"Failed to process attachment {attachment.get('filename', 'unknown')}: {e}")
+                    continue
+
+        # Get or create context
+        if context_id:
+            context = AgentContext.get(context_id)
+            if not context:
+                return Response('{"error": "Context not found"}', status=404, mimetype="application/json")
+        else:
+            config = initialize_agent()
+            context = AgentContext(config=config, type=AgentContextType.USER)
+            context_id = context.id
+
+        # Update chat lifetime
+        with self._cleanup_lock:
+            self._chat_lifetimes[context_id] = datetime.now() + timedelta(hours=lifetime_hours)
+
+        # Process message
+        try:
+            # Log the message
+            attachment_filenames = [os.path.basename(path) for path in attachment_paths] if attachment_paths else []
+
+            PrintStyle(
+                background_color="#6C3483", font_color="white", bold=True, padding=True
+            ).print("External API message:")
+            PrintStyle(font_color="white", padding=False).print(f"> {message}")
+            if attachment_filenames:
+                PrintStyle(font_color="white", padding=False).print("Attachments:")
+                for filename in attachment_filenames:
+                    PrintStyle(font_color="white", padding=False).print(f"- {filename}")
+
+            # Add user message to chat history so it's visible in the UI
+            context.log.log(
+                type="user",
+                heading="User message",
+                content=message,
+                kvps={"attachments": attachment_filenames},
+            )
+
+            # Send message to agent
+            task = context.communicate(UserMessage(message, attachment_paths))
+            result = await task.result()
+
+            # Clean up expired chats
+            self._cleanup_expired_chats()
+
+            return {
+                "context_id": context_id,
+                "response": result
+            }
+
+        except Exception as e:
+            PrintStyle.error(f"External API error: {e}")
+            return Response(f'{{"error": "{str(e)}"}}', status=500, mimetype="application/json")
+
+    @classmethod
+    def _cleanup_expired_chats(cls):
+        """Clean up expired chats"""
+        with cls._cleanup_lock:
+            now = datetime.now()
+            expired_contexts = [
+                context_id for context_id, expiry in cls._chat_lifetimes.items()
+                if now > expiry
+            ]
+
+            for context_id in expired_contexts:
+                try:
+                    context = AgentContext.get(context_id)
+                    if context:
+                        context.reset()
+                        AgentContext.remove(context_id)
+                    del cls._chat_lifetimes[context_id]
+                    PrintStyle().print(f"Cleaned up expired chat: {context_id}")
+                except Exception as e:
+                    PrintStyle.error(f"Failed to cleanup chat {context_id}: {e}")

python/api/api_reset_chat.py

@@ -0,0 +1,69 @@
+from agent import AgentContext
+from python.helpers.api import ApiHandler, Request, Response
+from python.helpers.print_style import PrintStyle
+from python.helpers import persist_chat
+import json
+
+
+class ApiResetChat(ApiHandler):
+    @classmethod
+    def requires_auth(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_csrf(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_api_key(cls) -> bool:
+        return True
+
+    @classmethod
+    def get_methods(cls) -> list[str]:
+        return ["POST"]
+
+    async def process(self, input: dict, request: Request) -> dict | Response:
+        try:
+            # Get context_id from input
+            context_id = input.get("context_id")
+
+            if not context_id:
+                return Response(
+                    '{"error": "context_id is required"}',
+                    status=400,
+                    mimetype="application/json"
+                )
+
+            # Check if context exists
+            context = AgentContext.get(context_id)
+            if not context:
+                return Response(
+                    '{"error": "Chat context not found"}',
+                    status=404,
+                    mimetype="application/json"
+                )
+
+            # Reset the chat context (clears history but keeps context alive)
+            context.reset()
+            # Save the reset context to persist the changes
+            persist_chat.save_tmp_chat(context)
+
+            # Log the reset
+            PrintStyle(
+                background_color="#3498DB", font_color="white", bold=True, padding=True
+            ).print(f"API Chat reset: {context_id}")
+
+            # Return success response
+            return {
+                "success": True,
+                "message": "Chat reset successfully",
+                "context_id": context_id
+            }
+
+        except Exception as e:
+            PrintStyle.error(f"API reset chat error: {str(e)}")
+            return Response(
+                json.dumps({"error": f"Internal server error: {str(e)}"}),
+                status=500,
+                mimetype="application/json"
+            )

python/api/api_terminate_chat.py

@@ -0,0 +1,68 @@
+from agent import AgentContext
+from python.helpers.api import ApiHandler, Request, Response
+from python.helpers.persist_chat import remove_chat
+from python.helpers.print_style import PrintStyle
+import json
+
+
+class ApiTerminateChat(ApiHandler):
+    @classmethod
+    def requires_auth(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_csrf(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_api_key(cls) -> bool:
+        return True
+
+    @classmethod
+    def get_methods(cls) -> list[str]:
+        return ["POST"]
+
+    async def process(self, input: dict, request: Request) -> dict | Response:
+        try:
+            # Get context_id from input
+            context_id = input.get("context_id")
+
+            if not context_id:
+                return Response(
+                    '{"error": "context_id is required"}',
+                    status=400,
+                    mimetype="application/json"
+                )
+
+            # Check if context exists
+            context = AgentContext.get(context_id)
+            if not context:
+                return Response(
+                    '{"error": "Chat context not found"}',
+                    status=404,
+                    mimetype="application/json"
+                )
+
+            # Delete the chat context
+            AgentContext.remove(context.id)
+            remove_chat(context.id)
+
+            # Log the deletion
+            PrintStyle(
+                background_color="#E74C3C", font_color="white", bold=True, padding=True
+            ).print(f"API Chat deleted: {context_id}")
+
+            # Return success response
+            return {
+                "success": True,
+                "message": "Chat deleted successfully",
+                "context_id": context_id
+            }
+
+        except Exception as e:
+            PrintStyle.error(f"API terminate chat error: {str(e)}")
+            return Response(
+                json.dumps({"error": f"Internal server error: {str(e)}"}),
+                status=500,
+                mimetype="application/json"
+            )

python/helpers/settings.py

@@ -67,7 +67,7 @@ class Settings(TypedDict):
     memory_memorize_enabled: bool
     memory_memorize_consolidation: bool
     memory_memorize_replace_threshold: float
-    
+
 
     api_keys: dict[str, str]
 
@@ -880,7 +880,7 @@ def convert_out(settings: Settings) -> SettingsOutput:
 
     # TTS fields
     tts_fields: list[SettingsField] = []
-    
+
     tts_fields.append(
         {
             "id": "tts_kokoro",
@@ -982,6 +982,28 @@ def convert_out(settings: Settings) -> SettingsOutput:
         "tab": "mcp",
     }
 
+    # External API section
+    external_api_fields: list[SettingsField] = []
+
+    external_api_fields.append(
+        {
+            "id": "external_api_examples",
+            "title": "API Examples",
+            "description": "View examples for using Agent Zero's external API endpoints with API key authentication.",
+            "type": "button",
+            "value": "Show API Examples",
+        }
+    )
+
+    external_api_section: SettingsSection = {
+        "id": "external_api",
+        "title": "External API",
+        "description": "Agent Zero provides external API endpoints for integration with other applications. "
+                       "These endpoints use API key authentication and support text messages and file attachments.",
+        "fields": external_api_fields,
+        "tab": "external",
+    }
+
     # Backup & Restore section
     backup_fields: list[SettingsField] = []
 
@@ -1030,6 +1052,7 @@ def convert_out(settings: Settings) -> SettingsOutput:
             auth_section,
             mcp_client_section,
             mcp_server_section,
+            external_api_section,
             backup_section,
             dev_section,
         ]

run_ui.py

@@ -1,18 +1,15 @@
 from datetime import timedelta
 import os
 import secrets
-import sys
 import time
 import socket
 import struct
 from functools import wraps
 import threading
-import signal
-from typing import override
 from flask import Flask, request, Response, session
 from flask_basicauth import BasicAuth
 import initialize
-from python.helpers import errors, files, git, mcp_server
+from python.helpers import files, git, mcp_server
 from python.helpers.files import get_abs_path
 from python.helpers import runtime, dotenv, process
 from python.helpers.extract_tools import load_classes_from_folder
@@ -81,14 +78,17 @@ def is_loopback_address(address):
 def requires_api_key(f):
     @wraps(f)
     async def decorated(*args, **kwargs):
-        valid_api_key = dotenv.get_dotenv_value("API_KEY")
+        # Use the auth token from settings (same as MCP server)
+        from python.helpers.settings import get_settings
+        valid_api_key = get_settings()["mcp_server_token"]
+
         if api_key := request.headers.get("X-API-KEY"):
             if api_key != valid_api_key:
-                return Response("API key required", 401)
+                return Response("Invalid API key", 401)
         elif request.json and request.json.get("api_key"):
             api_key = request.json.get("api_key")
             if api_key != valid_api_key:
-                return Response("API key required", 401)
+                return Response("Invalid API key", 401)
         else:
             return Response("API key required", 401)
         return await f(*args, **kwargs)
@@ -171,7 +171,7 @@ def run():
     from werkzeug.serving import WSGIRequestHandler
     from werkzeug.serving import make_server
     from werkzeug.middleware.dispatcher import DispatcherMiddleware
-    from a2wsgi import ASGIMiddleware, WSGIMiddleware
+    from a2wsgi import ASGIMiddleware
 
     PrintStyle().print("Starting server...")
 

webui/components/settings/external/api-examples.html

@@ -0,0 +1,678 @@
+<html>
+
+<head>
+    <title>Agent Zero External API Examples</title>
+</head>
+
+<body>
+    <div x-data>
+        <p>Agent Zero provides external API endpoints for integration with other applications.</p>
+        <p>These endpoints use API key authentication and support text messages and file attachments.</p>
+
+        <!-- API Token Information -->
+        <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 16px 0;">
+            <h4 style="margin: 0 0 8px 0; color: var(--color-text-primary);">API Token Information</h4>
+            <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                The API token is automatically generated from your username and password.
+                This same token is used for both MCP server connections and external API endpoints.
+                The token changes when you update your credentials.
+            </p>
+        </div>
+
+        <!-- Section 1: api_message Endpoint -->
+        <div class="api-section">
+            <h2>POST /api_message</h2>
+            <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">
+                Send messages to Agent Zero and receive responses. Supports text messages, file attachments, and conversation continuity.
+            </p>
+
+            <!-- API Reference -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>
+            <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
+                <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Parameters:</strong><br>
+                    • <code>context_id</code> (string, optional): Existing chat context ID<br>
+                    • <code>message</code> (string, required): The message to send<br>
+                    • <code>attachments</code> (array, optional): Array of {filename, base64} objects<br>
+                    • <code>lifetime_hours</code> (number, optional): Chat lifetime in hours (default: 24)
+                </p>
+                <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>
+                </p>
+            </div>
+
+            <!-- JavaScript Examples -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>
+
+            <h4>Basic Usage Example</h4>
+            <div id="api-basic-example"></div>
+
+            <h4>Conversation Continuation Example</h4>
+            <div id="api-continuation-example"></div>
+
+            <h4>File Attachment Example</h4>
+            <div id="api-attachment-example"></div>
+        </div>
+
+        <!-- Section 2: api_log_get Endpoint -->
+        <div class="api-section">
+            <h2>GET/POST /api_log_get</h2>
+            <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">
+                Retrieve log data by context ID, limited to a specified number of entries from the newest.
+            </p>
+
+            <!-- API Reference -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>
+            <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
+                <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Parameters:</strong><br>
+                    • <code>context_id</code> (string, required): Context ID to get logs from<br>
+                    • <code>length</code> (integer, optional): Number of log items to return from newest (default: 100)
+                </p>
+                <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code> (for POST)
+                </p>
+            </div>
+
+            <!-- JavaScript Examples -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>
+
+            <h4>GET Request Example</h4>
+            <div id="api-log-get-example"></div>
+
+            <h4>POST Request Example</h4>
+            <div id="api-log-post-example"></div>
+        </div>
+
+        <!-- Section 3: api_terminate_chat Endpoint -->
+        <div class="api-section">
+            <h2>POST /api_terminate_chat</h2>
+            <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">
+                Terminate and remove a chat context to free up resources. Similar to the MCP finish_chat function.
+            </p>
+
+            <!-- API Reference -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>
+            <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
+                <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Parameters:</strong><br>
+                    • <code>context_id</code> (string, required): Context ID of the chat to terminate
+                </p>
+                <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>
+                </p>
+            </div>
+
+            <!-- JavaScript Examples -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>
+            <h4>Basic Termination Examples</h4>
+            <div id="api-terminate-example"></div>
+        </div>
+
+        <!-- Section 4: api_reset_chat Endpoint -->
+        <div class="api-section">
+            <h2>POST /api_reset_chat</h2>
+            <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">
+                Reset a chat context to clear conversation history while keeping the context_id alive for continued use.
+            </p>
+
+            <!-- API Reference -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>
+            <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
+                <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Parameters:</strong><br>
+                    • <code>context_id</code> (string, required): Context ID of the chat to reset
+                </p>
+                <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>
+                </p>
+            </div>
+
+            <!-- JavaScript Examples -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>
+            <h4>Basic Reset Examples</h4>
+            <div id="api-reset-example"></div>
+        </div>
+
+        <!-- Section 5: api_files_get Endpoint -->
+        <div class="api-section">
+            <h2>POST /api_files_get</h2>
+            <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">
+                Retrieve file contents by paths, returning files as base64 encoded data. Useful for retrieving uploaded attachments.
+            </p>
+
+            <!-- API Reference -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>
+            <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
+                <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Parameters:</strong><br>
+                    • <code>paths</code> (array, required): Array of file paths to retrieve (e.g., ["/a0/tmp/uploads/file.txt"])
+                </p>
+                <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>
+                </p>
+            </div>
+
+            <!-- JavaScript Examples -->
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>
+            <h4>File Retrieval Examples</h4>
+            <div id="api-files-get-example"></div>
+        </div>
+
+        <!-- Section 6: Additional Endpoints -->
+        <!--
+        Example template for new endpoint sections:
+
+        <div class="api-section">
+            <h2>POST /endpoint_name</h2>
+            <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">
+                Description of what this endpoint does...
+            </p>
+
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>
+            <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
+                <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Parameters:</strong><br>
+                    • <code>param_name</code> (type, required/optional): Description
+                </p>
+                <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                    <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>
+                </p>
+            </div>
+
+            <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>
+            <h4>Example Title</h4>
+            <div id="example-id"></div>
+        </div>
+        -->
+
+        <script>
+            setTimeout(() => {
+                const url = window.location.origin;
+                const token = settingsModalProxy.settings.sections.filter(x => x.id == "mcp_server")[0].fields.filter(x => x.id == "mcp_server_token")[0].value;
+
+                // Basic usage example
+                const basicExample = `// Basic message example
+async function sendMessage() {
+    try {
+        const response = await fetch('${url}/api_message', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                message: "Hello, how can you help me?",
+                lifetime_hours: 24
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Success!');
+            console.log('Response:', data.response);
+            console.log('Context ID:', data.context_id);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Call the function
+sendMessage().then(result => {
+    if (result) {
+        console.log('Message sent successfully!');
+    }
+});`;
+
+                                // Continuation example
+                const continuationExample = `// Continue conversation example
+async function continueConversation(contextId) {
+    try {
+        const response = await fetch('${url}/api_message', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                context_id: contextId,
+                message: "Can you tell me more about that?",
+                lifetime_hours: 24
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Continuation Success!');
+            console.log('Response:', data.response);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Example: First send a message, then continue the conversation
+async function fullConversationExample() {
+    const firstResult = await sendMessage();
+    if (firstResult && firstResult.context_id) {
+        await continueConversation(firstResult.context_id);
+    }
+}
+
+fullConversationExample();`;
+
+                                // Attachment example
+                const attachmentExample = `// File attachment example
+async function sendWithAttachment() {
+    try {
+        // Example with text content (convert to base64)
+        const textContent = "Hello World from attachment!";
+        const base64Content = btoa(textContent);
+
+        const response = await fetch('${url}/api_message', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                message: "Please analyze this file:",
+                attachments: [
+                    {
+                        filename: "document.txt",
+                        base64: base64Content
+                    }
+                ],
+                lifetime_hours: 12
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ File sent successfully!');
+            console.log('Response:', data.response);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Call the function
+sendWithAttachment();`;
+
+                // Log GET example
+                const logGetExample = `// Get logs using GET request
+async function getLogsGET(contextId, length = 50) {
+    try {
+        const params = new URLSearchParams({
+            context_id: contextId,
+            length: length.toString()
+        });
+
+        const response = await fetch('${url}/api_log_get?' + params, {
+            method: 'GET',
+            headers: {
+                'X-API-KEY': '${token}'
+            }
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Logs retrieved successfully!');
+            console.log('Total items:', data.log.total_items);
+            console.log('Returned items:', data.log.returned_items);
+            console.log('Log items:', data.log.items);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Example usage
+getLogsGET('ctx_abc123', 20);`;
+
+                // Log POST example
+                const logPostExample = `// Get logs using POST request
+async function getLogsPOST(contextId, length = 50) {
+    try {
+        const response = await fetch('${url}/api_log_get', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                context_id: contextId,
+                length: length
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Logs retrieved successfully!');
+            console.log('Context ID:', data.context_id);
+            console.log('Log GUID:', data.log.guid);
+            console.log('Total items:', data.log.total_items);
+            console.log('Returned items:', data.log.returned_items);
+            console.log('Start position:', data.log.start_position);
+            console.log('Progress:', data.log.progress);
+            console.log('Log items:', data.log.items);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Example usage - get latest 10 log entries
+getLogsPOST('ctx_abc123', 10);`;
+
+                                                // Terminate chat example
+                const terminateExample = `// Basic terminate chat function
+async function terminateChat(contextId) {
+    try {
+        const response = await fetch('${url}/api_terminate_chat', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                context_id: contextId
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Chat deleted successfully!');
+            console.log('Message:', data.message);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Example 1: Terminate a specific chat
+terminateChat('ctx_abc123');
+
+// Example 2: Complete workflow - send message, then terminate
+async function simpleWorkflow() {
+    // Send a message
+    const result = await sendMessage();
+
+    if (result && result.context_id) {
+        console.log('Chat created:', result.context_id);
+
+        // Do some work with the chat...
+        // await continueConversation(result.context_id);
+
+        // Clean up when done
+        await terminateChat(result.context_id);
+        console.log('Chat cleaned up');
+    }
+}
+
+// Run the workflow
+simpleWorkflow();`;
+
+                // Reset chat example
+                const resetExample = `// Basic reset chat function
+async function resetChat(contextId) {
+    try {
+        const response = await fetch('${url}/api_reset_chat', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                context_id: contextId
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Chat reset successfully!');
+            console.log('Message:', data.message);
+            console.log('Context ID:', data.context_id);
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Example 1: Reset a specific chat
+resetChat('ctx_abc123');
+
+// Example 2: Reset and continue conversation
+async function resetAndContinue() {
+    const contextId = 'ctx_abc123';
+
+    // Reset the chat to clear history
+    const resetResult = await resetChat(contextId);
+
+    if (resetResult) {
+        console.log('Chat reset, starting fresh conversation...');
+
+        // Continue with same context_id but fresh history
+        const response = await fetch('${url}/api_message', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                context_id: contextId,  // Same context ID
+                message: "Hello, this is a fresh start!",
+                lifetime_hours: 24
+            })
+        });
+
+        const data = await response.json();
+        console.log('New conversation started:', data.response);
+    }
+}
+
+// Run the example
+resetAndContinue();`;
+
+                // Files get example
+                const filesGetExample = `// Basic file retrieval
+async function getFiles(filePaths) {
+    try {
+        const response = await fetch('${url}/api_files_get', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': '${token}'
+            },
+            body: JSON.stringify({
+                paths: filePaths
+            })
+        });
+
+        const data = await response.json();
+
+        if (response.ok) {
+            console.log('✅ Files retrieved successfully!');
+            console.log('Retrieved files:', Object.keys(data));
+
+            // Convert base64 back to text for display
+            for (const [filename, base64Content] of Object.entries(data)) {
+                try {
+                    const textContent = atob(base64Content);
+                    console.log(\`\${filename}: \${textContent.substring(0, 100)}...\`);
+                } catch (e) {
+                    console.log(\`\${filename}: Binary file (\${base64Content.length} chars)\`);
+                }
+            }
+
+            return data;
+        } else {
+            console.error('❌ Error:', data.error);
+            return null;
+        }
+    } catch (error) {
+        console.error('❌ Request failed:', error);
+        return null;
+    }
+}
+
+// Example 1: Get specific files
+const filePaths = [
+    "/a0/tmp/uploads/document.txt",
+    "/a0/tmp/uploads/data.json"
+];
+getFiles(filePaths);
+
+// Example 2: Complete attachment workflow
+async function attachmentWorkflow() {
+    // Step 1: Send message with attachments
+    const messageResponse = await fetch('${url}/api_message', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-API-KEY': '${token}'
+        },
+        body: JSON.stringify({
+            message: "Please analyze this file",
+            attachments: [{
+                filename: "test.txt",
+                base64: btoa("Hello, this is test content!")
+            }],
+            lifetime_hours: 1
+        })
+    });
+
+    if (messageResponse.ok) {
+        console.log('Message sent with attachment');
+
+        // Step 2: Retrieve the uploaded file
+        const retrievedFiles = await getFiles(["/a0/tmp/uploads/test.txt"]);
+
+        if (retrievedFiles && retrievedFiles["test.txt"]) {
+            const originalContent = atob(retrievedFiles["test.txt"]);
+            console.log('Retrieved content:', originalContent);
+        }
+    }
+}
+
+// Run the complete workflow
+attachmentWorkflow();`;
+
+                // Initialize ACE editors
+                const editors = [
+                    { id: "api-basic-example", content: basicExample },
+                    { id: "api-continuation-example", content: continuationExample },
+                    { id: "api-attachment-example", content: attachmentExample },
+                    { id: "api-log-get-example", content: logGetExample },
+                    { id: "api-log-post-example", content: logPostExample },
+                    { id: "api-terminate-example", content: terminateExample },
+                    { id: "api-reset-example", content: resetExample },
+                    { id: "api-files-get-example", content: filesGetExample }
+                ];
+
+                editors.forEach(({ id, content }) => {
+                    const editor = ace.edit(id);
+                    const dark = localStorage.getItem("darkMode");
+                    if (dark != "false") {
+                        editor.setTheme("ace/theme/github_dark");
+                    } else {
+                        editor.setTheme("ace/theme/tomorrow");
+                    }
+                    editor.session.setMode("ace/mode/javascript");
+                    editor.setValue(content);
+                    editor.clearSelection();
+                    editor.setReadOnly(true);
+                });
+            }, 0);
+        </script>
+    </div>
+
+    <style>
+        #api-basic-example,
+        #api-continuation-example,
+        #api-attachment-example,
+        #api-log-get-example,
+        #api-log-post-example,
+        #api-terminate-example,
+        #api-reset-example,
+        #api-files-get-example {
+            width: 100%;
+            height: 20em;
+            margin: 8px 0 16px 0;
+            border-radius: 4px;
+        }
+
+        /* Section styling */
+        .api-section {
+            border: 1px solid var(--color-border);
+            border-radius: 8px;
+            margin: 20px 0;
+            padding: 16px;
+        }
+
+        .api-section h2 {
+            margin: 0 0 16px 0;
+            color: var(--color-text-primary);
+            border-bottom: 1px solid var(--color-border);
+            padding-bottom: 8px;
+        }
+
+        .api-section h3 {
+            margin: 20px 0 12px 0;
+            color: var(--color-text-primary);
+            font-size: 1.2em;
+        }
+
+        .api-section h4 {
+            margin: 16px 0 8px 0;
+            color: var(--color-text-primary);
+        }
+    </style>
+
+</body>
+
+</html>

webui/components/settings/mcp/server/example.html

@@ -10,6 +10,15 @@
         <p>Agent Zero MCP Server is an SSE MCP running on the same URL and port as the Web UI + /mcp/sse path.</p>
         <p>The same applies if you run A0 on a public URL using a tunnel.</p>
 
+        <!-- API Token Information -->
+        <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 16px 0;">
+            <h4 style="margin: 0 0 8px 0; color: var(--color-text-primary);">API Token Information</h4>
+            <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
+                The token used in the URL is automatically generated from your username and password.
+                This same token is also used for external API endpoints. The token changes when you update your credentials.
+            </p>
+        </div>
+
         <h3>Example MCP Server Configuration JSON</h3>
         <div id="mcp-server-example"></div>
 
@@ -52,4 +61,4 @@
 
 </body>
 
-</html>
+</html>

webui/js/settings.js

@@ -291,6 +291,8 @@ const settingsModalProxy = {
             openModal("settings/backup/backup.html");
         } else if (field.id === "backup_restore") {
             openModal("settings/backup/restore.html");
+        } else if (field.id === "external_api_examples") {
+            openModal("settings/external/api-examples.html");
         }
     }
 };