API Reference

Complete REST API documentation for integrating with SAM.

SAM provides a built-in REST API that's compatible with OpenAI's formatfor integrating SAM into your applications, scripts, and workflows. Use it for building custom UIs, automating tasks, or connecting SAM to larger systems. The API gives you programmatic access to all of SAM's capabilities.

What's covered: - Complete endpoint reference with examples - OpenAI-compatible chat completions API - Conversation management endpoints - Memory and RAG API endpoints - Streaming responses with SSE - Error handling and best practices

Why use the API: - Build custom frontends and UIs - Integrate SAM into existing applications - Automate workflows with scripts - Create specialized tools and interfaces - Access SAM from other programming languages

Prerequisites: - Basic understanding of REST APIs - Familiarity with JSON - Knowledge of HTTP methods (GET, POST, DELETE) - Optional: Understanding of Server-Sent Events (SSE) for streaming

---

Base URL

http://localhost:8080

Default port: 8080 (configurable in preferences)

---

Authentication

Currently no authentication required for localhost.
For remote access, configure authentication in SAM preferences.

---

Endpoints

POST /api/chat/completions

Send a chat message and receive a response.

Request Body:

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "max_tokens": 2000,
  "stream": false,
  "tools": []
}

Response (non-streaming):

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1699123456,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 28,
    "total_tokens": 43
  },
  "sam_metadata": {
    "provider": {
      "type": "openai",
      "name": "OpenAI",
      "is_local": false,
      "base_url": "api.openai.com"
    },
    "model_info": {
      "context_window": 8192,
      "max_output_tokens": 8192,
      "supports_tools": true,
      "supports_vision": false,
      "supports_streaming": true,
      "family": "gpt-4"
    },
    "workflow": {
      "iterations": 1,
      "max_iterations": 300,
      "tool_call_count": 0,
      "tools_used": [],
      "duration_seconds": 2.5,
      "completion_reason": "workflow_complete",
      "had_errors": false
    },
    "cost_estimate": {
      "estimated_cost_usd": 0.0012,
      "prompt_cost_per_1k": 0.03,
      "completion_cost_per_1k": 0.06,
      "currency": "USD",
      "note": "Estimated based on published pricing"
    }
  }
}

SAM Enhanced Metadata

SAM enriches API responses with comprehensive metadata in the sam_metadata field:

Field	Description
provider	Provider info: type, name, local/remote status, base URL
model_info	Model capabilities: context window, output limits, tool/vision/streaming support
workflow	Execution details: iterations, tool calls, duration, completion reason
cost_estimate	USD cost estimate with per-1K token rates

Provider Types: openai, github-copilot, deepseek, gemini, minimax, openrouter, local-llama, local-mlx, remote-llama, ollama-cloud, zai, zai-coding, custom

Completion Reasons: workflow_complete, max_iterations_reached, cancelled, error, tool_execution_failed

Response (streaming with stream: true):

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699123456,"model":"gpt-4","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699123456,"model":"gpt-4","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: [DONE]

GET /api/models

List available models.

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "owned_by": "openai"
    },
    {
      "id": "mlx-qwen-7b",
      "object": "model",
      "owned_by": "local"
    }
  ]
}

Common Parameters

Parameter	Type	Description	Default
model	string	Model to use	Required
messages	array	Conversation messages	Required
temperature	number	Randomness (0.0-2.0)	0.7
max_tokens	integer	Max response length	2000
top_p	number	Nucleus sampling	1.0
stream	boolean	Enable streaming	false
tools	array	Available tools	[]

Message Format

{
  "role": "user|assistant|system|tool",
  "content": "Message content",
  "tool_calls": [] // For assistant messages with tool calls
}

POST /api/chat/tool-response

Submit user response for blocked tool execution (User Collaboration Protocol).

Request Body:

{
  "toolCallId": "call_abc123",
  "userResponse": "yes",
  "conversationId": "uuid-here"
}

---

POST /api/chat/autonomous

Multi-step autonomous workflow endpoint with agent orchestration.

Request Body:

{
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "Build a todo app"}],
  "maxIterations": 50
}

---

GET /v1/conversations

List all conversations.

Response:

{
  "conversations": [
    {
      "id": "uuid",
      "title": "My Conversation",
      "messageCount": 42
    }
  ]
}

---

GET /v1/conversations/:conversationId

Get specific conversation details.

---

GET /api/prompts/system

List available system prompts.

---

GET /api/prompts/mini

List available mini prompts.

---

GET /api/topics

List shared topics for cross-conversation collaboration.

Response:

{
  "topics": [
    {
      "id": "project-alpha",
      "name": "Project Alpha",
      "created_at": "2026-01-05T10:30:00Z",
      "conversation_count": 3
    }
  ]
}

---

GET /api/models/download/:downloadId/status

Check download status.

---

DELETE /api/models/download/:downloadId

Cancel ongoing download.

---

GET /api/tool_result

Retrieve large persisted tool results (>16KB auto-persist).

Query Parameters: - resultId (string): Tool result ID

---

GET /debug/mcp/tools

List all MCP tools with complete schemas (for debugging).

Response:

{
  "tools": [
    {
      "name": "file_operations",
      "description": "File operations: read, search, write, and manage workspace files",
      "inputSchema": {
        "type": "object",
        "properties": {
          "operation": {"type": "string", "enum": ["read_file", "list_dir", ...]},
          "filePath": {"type": "string"}
        }
      }
    }
  ]
}

---

POST /debug/mcp/execute

Execute an MCP tool directly (bypassing AI, for testing).

Request Body:

{
  "tool": "file_operations",
  "arguments": {
    "operation": "read_file",
    "filePath": "/path/to/file.txt",
    "startLine": 1,
    "endLine": 10
  }
}

Response:

{
  "success": true,
  "result": "File content here...",
  "execution_time_ms": 45
}

---

GET /debug/tools/available

Get tool registry status and availability.

Response:

{
  "total_tools": 16,
  "enabled_tools": 12,
  "disabled_tools": 4,
  "tools": [
    {"name": "file_operations", "enabled": true, "operation_count": 16},
    {"name": "terminal_operations", "enabled": false, "operation_count": 1}
  ]
}

---

---

Tool Calling

SAM provides MCP (Model Context Protocol) tools that the AI can automatically invoke to complete tasks. For complete tool documentation, see Tools Reference.

Available Tools

SAM includes the following tools:

Tool	Operations	Status	Description
think	1	Enabled	Planning and structured reasoning
increase_max_iterations	1	Enabled	Request more iterations for complex tasks
read_tool_result	1	Enabled	Retrieve large persisted tool results
user_collaboration	1	Enabled	Pause for user input, decisions, or approval
file_operations	18	Enabled	Read, write, edit, and search files
terminal_operations	1	Enabled	Execute shell commands
memory_operations	14	Enabled	Store, search, and recall memories
todo_operations	4	Enabled	Manage structured todo lists
web_operations	3	Enabled	Web research, search, fetch
document_operations	3	Enabled	Import, create, and manage documents
calendar_operations	9	Enabled	macOS Calendar integration
contacts_operations	6	Enabled	macOS Contacts integration
notes_operations	6	Enabled	Apple Notes integration
spotlight_search	5	Enabled	macOS Spotlight search
weather_operations	3	Enabled	Current weather and forecast
image_generation	2	Enabled	Generate images via remote ALICE
math_operations	4	Enabled	Calculate, convert, and run formula math
code_intelligence	2	Enabled	Find symbol usages and search commit history
version_control	9	Enabled	Git version control operations
remote_execution	5	Enabled	Run tasks on remote systems over SSH
apply_patch	1	Enabled	Apply multi-file patches
agent_operations	7	Enabled	Spawn and coordinate sub-agents

Note: SAM provides 22 tools (78 operations total). Core tools are automatically available to the AI. Advanced tools (terminal, subagent, remote execution) are disabled by default for security and can be enabled via API or UI preferences.

Tool Invocation Format

Tools are invoked using OpenAI's function calling format. For consolidated tools, include the operation parameter:

Request with tools:

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "Read the README file"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "file_operations",
        "description": "File operations: read, search, write, and manage workspace files",
        "parameters": {
          "type": "object",
          "properties": {
            "operation": {
              "type": "string",
              "description": "File operation to perform",
              "enum": ["read_file", "list_dir", "create_file", "replace_string", ...]
            },
            "filePath": {
              "type": "string",
              "description": "File path for read/write operations"
            }
          },
          "required": ["operation"]
        }
      }
    }
  ]
}

Model's tool call:

{
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "file_operations",
      "arguments": "{\"operation\":\"read_file\",\"filePath\":\"/path/to/README.md\"}"
    }
  }]
}

Tool result response:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "name": "file_operations",
  "content": "{\"success\":true,\"content\":\"# README\\n\\nThis is the README file...\"}"
}

Common Tool Calling Patterns

Read a file:

{
  "name": "file_operations",
  "arguments": {
    "operation": "read_file",
    "filePath": "/project/src/main.swift"
  }
}

Search code:

{
  "name": "file_operations",
  "arguments": {
    "operation": "grep_search",
    "query": "func.*authenticate",
    "isRegexp": true,
    "includePattern": "**/*.swift"
  }
}

Execute terminal command:

{
  "name": "terminal_operations",
  "arguments": {
    "operation": "run_command",
    "command": "npm install",
    "explanation": "Install project dependencies"
  }
}

Search conversation memory:

{
  "name": "memory_operations",
  "arguments": {
    "operation": "search_memory",
    "query": "API configuration",
    "similarity_threshold": "0.3"
  }
}

Git commit:

{
  "name": "version_control",
  "arguments": {
    "operation": "git_commit",
    "message": "feat: Add authentication module",
    "files": ["src/auth.swift", "tests/auth_test.swift"]
  }
}

Tool Response Format

Tool results are returned as JSON strings in the content field:

Success response:

{
  "success": true,
  "data": "Tool execution result",
  "message": "Operation completed successfully"
}

Error response:

{
  "success": false,
  "error": "Error message",
  "message": "Operation failed"
}

Multi-Turn Tool Calling

Complex tasks may require multiple tool calls. The conversation continues with tool results:

// Turn 1: User request
{"role": "user", "content": "Find and update the version number"}

// Turn 2: AI calls search tool
{"role": "assistant", "tool_calls": [{"function": {"name": "file_operations", "arguments": "{\"operation\":\"grep_search\",\"query\":\"version\"}"}}]}

// Turn 3: Tool result
{"role": "tool", "content": "Found in config.json: \"version\": \"1.0.0\""}

// Turn 4: AI calls edit tool
{"role": "assistant", "tool_calls": [{"function": {"name": "file_operations", "arguments": "{\"operation\":\"replace_string\",\"filePath\":\"config.json\",\"oldString\":\"\\\"version\\\": \\\"1.0.0\\\"\",\"newString\":\"\\\"version\\\": \\\"1.1.0\\\"\"}"}}]}

// Turn 5: Tool result
{"role": "tool", "content": "{\"success\": true}"}

// Turn 6: AI response
{"role": "assistant", "content": "Version number updated from 1.0.0 to 1.1.0"}

Tool Authorization

Some operations require user authorization:

• Auto-approved: Read operations, write operations inside working directory
• Require approval: Write operations outside working directory, destructive operations

When authorization is required, the AI can use the user_collaboration tool:

{
  "name": "user_collaboration",
  "arguments": {
    "prompt": "May I delete the old backup files?",
    "authorize_operation": "file_operations.delete_file"
  }
}

---

Examples

Simple Chat

curl -X POST http://localhost:8080/api/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "What is 2+2?"}
    ]
  }'

Streaming Response

curl -N -X POST http://localhost:8080/api/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "Write a poem"}
    ],
    "stream": true
  }'

With SAM Tools

Note: SAM's built-in tools are automatically available. This example shows how to use them via the API:

curl -X POST http://localhost:8080/api/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "Read the package.json file"}
    ]
  }'

The AI will automatically invoke file_operations with operation: read_file.

For custom tool integrations:

curl -X POST http://localhost:8080/api/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "Search for authentication code"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "file_operations",
          "description": "File operations",
          "parameters": {
            "type": "object",
            "properties": {
              "operation": {"type": "string", "enum": ["grep_search"]},
              "query": {"type": "string"},
              "isRegexp": {"type": "boolean"}
            },
            "required": ["operation"]
          }
        }
      }
    ]
  }'

---

Error Handling

Error Response Format:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Common Error Codes: - invalid_request_error - Malformed request - authentication_error - Invalid API key - rate_limit_error - Too many requests - server_error - Internal server error

---

Rate Limits

SAM does not impose rate limits for localhost access.
For remote access, configure rate limits in preferences.

---

SDK Examples

Python

import openai

openai.api_base = "http://localhost:8080/api"
openai.api_key = "not-needed-for-local"

response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response.choices[0].message.content)

JavaScript

const response = await fetch('http://localhost:8080/api/chat/completions', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{role: 'user', content: 'Hello'}]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

---

For more examples, see Developer's Guide.