Skip to content

Agent Zero AI framework

feat: External API Endpoints

Rafael Uzarowskie74dabb40ac9
diff --git a/python/api/api_files_get.py b/python/api/api_files_get.py
new file mode 100644
index 000000000..e021af60f
--- /dev/null
+++ b/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"
+ )
diff --git a/python/api/api_log_get.py b/python/api/api_log_get.py
new file mode 100644
index 000000000..c09fdfdc0
--- /dev/null
+++ b/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")
diff --git a/python/api/api_message.py b/python/api/api_message.py
new file mode 100644
index 000000000..4d3248c60
--- /dev/null
+++ b/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}")
diff --git a/python/api/api_reset_chat.py b/python/api/api_reset_chat.py
new file mode 100644
index 000000000..b497adb1e
--- /dev/null
+++ b/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"
+ )
diff --git a/python/api/api_terminate_chat.py b/python/api/api_terminate_chat.py
new file mode 100644
index 000000000..3d6bcb4b4
--- /dev/null
+++ b/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"
+ )
diff --git a/python/helpers/settings.py b/python/helpers/settings.py
index 4ea9a23eb..d0f80e537 100644
--- a/python/helpers/settings.py
+++ b/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,
]
diff --git a/run_ui.py b/run_ui.py
index 07ae1c82f..0b1b80c97 100644
--- a/run_ui.py
+++ b/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...")
diff --git a/webui/components/settings/external/api-examples.html b/webui/components/settings/external/api-examples.html
new file mode 100644
index 000000000..08569a1e9
--- /dev/null
+++ b/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>
diff --git a/webui/components/settings/mcp/server/example.html b/webui/components/settings/mcp/server/example.html
index 75bcd815c..b69c28ad1 100644
--- a/webui/components/settings/mcp/server/example.html
+++ b/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>
\ No newline at end of file
+</html>
diff --git a/webui/js/settings.js b/webui/js/settings.js
index f58cb1c97..aa36d7e91 100644
--- a/webui/js/settings.js
+++ b/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");
}
}
};
diff --git a/webui/public/external_api.svg b/webui/public/external_api.svg
new file mode 100644
index 000000000..5dc4f86b2
--- /dev/null
+++ b/webui/public/external_api.svg
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
+ <g fill="none" stroke="#000" stroke-width="0.8" stroke-miterlimit="10">
+ <!-- Central hub node -->
+ <circle cx="10" cy="10" r="2.5"/>
+
+ <!-- External connection nodes -->
+ <circle cx="3" cy="3" r="1.5"/>
+ <circle cx="17" cy="3" r="1.5"/>
+ <circle cx="3" cy="17" r="1.5"/>
+ <circle cx="17" cy="17" r="1.5"/>
+
+ <!-- Connection lines -->
+ <line x1="5.1" y1="4.9" x2="7.9" y2="7.1"/>
+ <line x1="14.9" y1="4.9" x2="12.1" y2="7.1"/>
+ <line x1="5.1" y1="15.1" x2="7.9" y2="12.9"/>
+ <line x1="14.9" y1="15.1" x2="12.1" y2="12.9"/>
+
+ <!-- API endpoints indicators -->
+ <rect x="1" y="7" width="1" height="6" rx="0.5"/>
+ <rect x="18" y="7" width="1" height="6" rx="0.5"/>
+ <rect x="7" y="1" width="6" height="1" rx="0.5"/>
+ <rect x="7" y="18" width="6" height="1" rx="0.5"/>
+
+ <!-- Data flow arrows -->
+ <path d="M6 8.5 L7.5 9.5 L6 10.5" fill="none" stroke-width="0.6"/>
+ <path d="M14 9.5 L12.5 8.5 L14 7.5" fill="none" stroke-width="0.6"/>
+ </g>
+</svg>