Local API - Complete Endpoint Reference

Complete reference for all endpoints in the AGNT Local Backend API (http://localhost:3333/api).

Table of Contents

• Agents
• Goals
• Orchestrator
• Workflows
• Executions
• Tools
• Custom Tools
• MCP Servers
• NPM Search
• Models
• Streaming
• Speech
• Users
• Webhooks
• Tool Schemas

Agents

Local agent management and execution.

Base: /agents

List Agents

GET /agents

Auth: Required

Get Agent

GET /agents/:id

Auth: Required

Save Agent

POST /agents/save
PUT /agents/:id

Auth: Required

Body:

{
  "name": "Local Agent",
  "model": "gpt-4",
  "systemPrompt": "You are a helpful assistant",
  "temperature": 0.7,
  "tools": ["web_search"]
}

Delete Agent

DELETE /agents/:id

Auth: Required

Chat with Agent

POST /agents/:id/chat

Auth: Required

Body:

{
  "message": "Hello, how can you help me?",
  "conversationHistory": [],
  "stream": false
}

Response:

{
  "success": true,
  "response": "I can help you with various tasks...",
  "tokensUsed": 150,
  "model": "gpt-4"
}

Stream Chat with Agent

POST /agents/:id/chat-stream

Auth: Required | Content-Type: multipart/form-data

Response: Server-Sent Events stream

Get Agent Suggestions

POST /agents/:id/suggestions

Auth: Required

Body:

{
  "context": "Current conversation context",
  "count": 3
}

Response:

{
  "suggestions": ["Tell me more about...", "Can you explain...", "What about..."]
}

Goals

Goal-based agent execution with evaluation and golden standards.

Base: /goals

List Goals

GET /goals

Auth: Required

Get Goal

GET /goals/:id

Auth: Required

Create Goal

POST /goals/create

Auth: Required

Body:

{
  "description": "Research and summarize AI trends",
  "agentId": "agent-123",
  "successCriteria": ["Comprehensive research", "Clear summary", "Cited sources"],
  "maxIterations": 10
}

Response:

{
  "success": true,
  "goalId": "goal-456",
  "status": "created"
}

Execute Goal

POST /goals/:goalId/execute

Auth: Required

Starts goal execution. The agent will work autonomously to achieve the goal.

Get Goal Status

GET /goals/:id/status

Auth: Required

Response:

{
  "id": "goal-456",
  "status": "in_progress",
  "progress": 60,
  "currentStep": "Analyzing data",
  "iterations": 3,
  "maxIterations": 10,
  "startedAt": "2025-11-25T10:00:00Z"
}

Pause Goal

POST /goals/:id/pause

Auth: Required

Resume Goal

POST /goals/:id/resume

Auth: Required

Delete Goal

DELETE /goals/:id

Auth: Required

Evaluate Goal

POST /goals/:id/evaluate

Auth: Required

Body:

{
  "criteria": ["accuracy", "completeness", "clarity"],
  "compareToGoldenStandard": true
}

Response:

{
  "score": 85,
  "breakdown": {
    "accuracy": 90,
    "completeness": 80,
    "clarity": 85
  },
  "feedback": "Good performance overall...",
  "goldenStandardComparison": {
    "similarity": 0.92,
    "differences": ["Minor formatting differences"]
  }
}

Get Evaluation Report

GET /goals/:id/evaluation

Auth: Required

Save as Golden Standard

POST /goals/:id/golden-standard

Auth: Required

Saves the goal's output as a golden standard for future comparisons.

List Golden Standards

GET /goals/golden-standards/list

Auth: Required

Orchestrator

Universal chat handler for all agent types (agents, workflows, tools, goals).

Base: /orchestrator

Universal Chat

POST /orchestrator/chat
POST /orchestrator/agent-chat
POST /orchestrator/workflow-chat
POST /orchestrator/tool-chat
POST /orchestrator/goal-chat

Auth: Required | Content-Type: multipart/form-data

Body:

• message - User message (required)
• files - File uploads (optional)
• agentId - Agent ID (for agent-chat)
• workflowId - Workflow ID (for workflow-chat)
• toolId - Tool ID (for tool-chat)
• goalId - Goal ID (for goal-chat)
• stream - Enable streaming (default: true)
• conversationHistory - Previous messages

Response: Server-Sent Events stream or JSON

Example:

const formData = new FormData();
formData.append('message', 'Analyze this document');
formData.append('files', fileBlob, 'document.pdf');
formData.append('agentId', 'agent-123');
formData.append('stream', 'true');

const response = await fetch('http://localhost:3333/api/orchestrator/agent-chat', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
  },
  body: formData,
});

// Handle SSE stream
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  console.log('Received:', chunk);
}

Get Suggestions

POST /orchestrator/suggestions

Auth: Required

Body:

{
  "context": "Current conversation",
  "type": "agent",
  "id": "agent-123"
}

Workflows

Workflow execution and management.

Base: /workflows

List Workflows

GET /workflows

Auth: Required

Get Workflow

GET /workflows/:id

Auth: Required

Save Workflow

POST /workflows/save
PUT /workflows/:id

Auth: Required

Body:

{
  "name": "Content Pipeline",
  "description": "Automated content creation",
  "nodes": [
    {
      "id": "node-1",
      "type": "agent",
      "config": {
        "agentId": "agent-123"
      }
    }
  ],
  "edges": [
    {
      "source": "node-1",
      "target": "node-2"
    }
  ]
}

Delete Workflow

DELETE /workflows/:id

Auth: Required

Rename Workflow

PUT /workflows/:id/name

Auth: Required

Body: { "name": "New Workflow Name" }

Get Workflow Status

GET /workflows/:id/status

Auth: Required

Response:

{
  "id": "workflow-123",
  "status": "running",
  "currentNode": "node-2",
  "progress": 50,
  "startedAt": "2025-11-25T10:00:00Z"
}

Start Workflow

POST /workflows/:id/start

Auth: Required

Body:

{
  "inputs": {
    "topic": "AI trends",
    "format": "blog post"
  }
}

Stop Workflow

POST /workflows/:id/stop

Auth: Required

Executions

Execution history and details.

Base: /executions

List Executions

GET /executions

Auth: Required

Query Params:

• page - Page number
• limit - Items per page
• status - Filter by status
• agentId - Filter by agent
• workflowId - Filter by workflow

Get Execution Details

GET /executions/:id

Auth: Required

Response:

{
  "id": "exec-123",
  "type": "agent",
  "agentId": "agent-456",
  "status": "completed",
  "startedAt": "2025-11-25T10:00:00Z",
  "completedAt": "2025-11-25T10:05:00Z",
  "duration": 300000,
  "tokensUsed": 2500,
  "cost": 0.05,
  "input": "Research AI trends",
  "output": "Comprehensive research report...",
  "steps": [
    {
      "name": "Web Search",
      "status": "success",
      "duration": 5000
    }
  ]
}

Get Agent Activity

POST /executions/activity

Auth: Required

Body:

{
  "agentId": "agent-123",
  "startDate": "2025-11-01",
  "endDate": "2025-11-30",
  "groupBy": "day"
}

Response:

{
  "totalExecutions": 150,
  "successRate": 95,
  "avgDuration": 45000,
  "totalTokens": 125000,
  "timeline": [
    {
      "date": "2025-11-25",
      "executions": 10,
      "tokens": 5000
    }
  ]
}

Tools

Tool management and available tools.

Base: /tools

Get Orchestrator Tools

GET /tools/orchestrator-tools

Auth: Required

Response:

{
  "tools": [
    {
      "id": "web_search",
      "name": "Web Search",
      "title": "Web Search",
      "description": "Search the web for information",
      "category": "Data & Knowledge",
      "is_builtin": true
    },
    {
      "id": "execute_shell",
      "name": "Execute Shell",
      "description": "Execute shell commands",
      "category": "Productivity",
      "is_builtin": true
    }
  ]
}

Custom Tools

Custom tool definitions.

Base: /custom-tools

List Custom Tools

GET /custom-tools

Auth: Required

Get Custom Tool

GET /custom-tools/:id

Auth: Required

Save Custom Tool

POST /custom-tools/save
PUT /custom-tools/:id

Auth: Required

Body:

{
  "name": "Weather API",
  "description": "Fetch weather data",
  "type": "api",
  "config": {
    "url": "https://api.weather.com/v1/current",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer API_KEY"
    },
    "params": {
      "location": "{{location}}"
    }
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["location"]
  }
}

Delete Custom Tool

DELETE /custom-tools/:id

Auth: Required

MCP Servers

Model Context Protocol server management.

Base: /mcp

List MCP Servers

GET /mcp/servers

Auth: Required

Response:

{
  "servers": [
    {
      "name": "weather-server",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-weather"],
      "env": {},
      "status": "running",
      "capabilities": {
        "tools": ["get_weather", "get_forecast"],
        "resources": []
      }
    }
  ]
}

Add MCP Server

POST /mcp/servers

Auth: Required

Body:

{
  "name": "custom-server",
  "command": "node",
  "args": ["server.js"],
  "env": {
    "API_KEY": "your-key"
  }
}

Update MCP Server

PUT /mcp/servers/:name

Auth: Required

Delete MCP Server

DELETE /mcp/servers/:name

Auth: Required

Get Server Capabilities

GET /mcp/servers/:name/capabilities

Auth: Required

Response:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather",
      "inputSchema": {}
    }
  ],
  "resources": [],
  "prompts": []
}

Test MCP Server Connection

POST /mcp/servers/:name/test

Auth: Required

Response:

{
  "success": true,
  "status": "connected",
  "latency": 45,
  "capabilities": {
    "tools": 5,
    "resources": 2
  }
}

NPM Search

Search NPM for MCP server packages.

Base: /npm

Search MCP Servers

GET /npm/search?q=weather

Auth: Required

Query Params:

• q - Search query
• page - Page number
• limit - Results per page

Response:

{
  "packages": [
    {
      "name": "@modelcontextprotocol/server-weather",
      "version": "1.0.0",
      "description": "MCP server for weather data",
      "author": "MCP Team",
      "downloads": 5000,
      "repository": "https://github.com/..."
    }
  ],
  "total": 25
}

Get Popular Servers

GET /npm/popular

Auth: Required

Get Package Details

GET /npm/package/:packageName

Auth: Required

Response:

{
  "name": "@modelcontextprotocol/server-weather",
  "version": "1.0.0",
  "description": "MCP server for weather data",
  "readme": "# Weather Server\n\n...",
  "dependencies": {},
  "repository": "https://github.com/...",
  "homepage": "https://..."
}

Test Package

POST /npm/test

Auth: Required

Body:

{
  "packageName": "@modelcontextprotocol/server-weather",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-weather"]
}

Models

AI model management and selection.

Base: /models

Get Models by Provider

GET /models/:provider/models

Auth: Required

Path Params:

• provider - Provider name (openrouter, anthropic, openai, gemini, groq, togetherai, grok)

Query Params:

• category - Filter by category
• useCache - Use cached results (default: true)
• format - Response format (names, full)

Example:

GET /models/openrouter/models?category=programming&format=names

Response:

{
  "success": true,
  "models": ["gpt-4-turbo", "gpt-4", "claude-3-opus", "claude-3-sonnet"],
  "cached": true,
  "count": 4
}

Refresh Models Cache

POST /models/:provider/models/refresh

Auth: Required

Get Model Categories

GET /models/models/categories

Auth: Required

Response:

{
  "success": true,
  "categories": [
    {
      "id": "all",
      "name": "All Models",
      "description": "All available models"
    },
    {
      "id": "programming",
      "name": "Programming",
      "description": "Models optimized for code generation"
    }
  ]
}

Streaming

Real-time AI streaming.

Base: /stream

Start Tool Forge Stream

POST /stream/start-tool-forge-stream

Auth: Required | Content-Type: multipart/form-data

Cancel Tool Forge Stream

POST /stream/cancel-tool-forge-stream

Auth: Required

Start Chat Stream

POST /stream/start-chat-stream

Auth: Required | Content-Type: multipart/form-data

Cancel Chat Stream

POST /stream/cancel-chat-stream

Auth: Required

Generate Tool

POST /stream/generate-tool

Auth: Required

Body:

{
  "description": "A tool that converts currencies",
  "requirements": ["Real-time exchange rates", "Multiple currencies"]
}

Generate Workflow

POST /stream/generate-workflow

Auth: Required

Generate Agent

POST /stream/generate-agent

Auth: Required

Body:

{
  "description": "Customer support agent",
  "capabilities": ["Answer FAQs", "Escalate issues"],
  "tone": "friendly and professional"
}

Speech

Speech-to-text services using Whisper.

Base: /speech

Transcribe Audio

POST /speech/transcribe

Auth: Required | Content-Type: multipart/form-data

Body:

• audio - Audio file (webm, wav, mp3, ogg, m4a)

Example:

const formData = new FormData();
formData.append('audio', audioBlob, 'recording.webm');

const response = await fetch('http://localhost:3333/api/speech/transcribe', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
  },
  body: formData,
});

const data = await response.json();
console.log('Transcript:', data.transcript);

Response:

{
  "success": true,
  "transcript": "Hello, this is a test transcription."
}

Get Whisper Status

GET /speech/status

Auth: Required

Response:

{
  "success": true,
  "initialized": true,
  "modelPath": "/path/to/whisper/model",
  "modelSize": "base"
}

Initialize Whisper

POST /speech/initialize

Auth: Required

Downloads Whisper model if not already present.

Users

User settings and preferences.

Base: /users

Get User Stats

GET /users/user-stats

Auth: Required

Response:

{
  "totalAgents": 10,
  "totalWorkflows": 5,
  "totalExecutions": 250,
  "totalGoals": 3
}

Get User Settings

GET /users/settings

Auth: Required

Update User Settings

PUT /users/settings

Auth: Required

Body:

{
  "theme": "dark",
  "defaultModel": "gpt-4",
  "autoSave": true,
  "notifications": {
    "email": true,
    "desktop": true
  }
}

Sync Token

POST /users/sync-token

Auth: Required

Syncs authentication token from remote API.

Get Token Status

GET /users/token-status

Auth: Not required

Response:

{
  "hasToken": true,
  "isValid": true,
  "expiresAt": "2025-12-25T10:00:00Z"
}

Get Connection Health

GET /users/connection-health

Auth: Required

Response:

{
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "status": "connected",
      "lastChecked": "2025-11-25T10:00:00Z"
    }
  ]
}

Get Single Provider Health

GET /users/connection-health/:providerId

Auth: Required

Connection Health Stream

GET /users/connection-health-stream?token=YOUR_JWT_TOKEN

Auth: Via query parameter

Response: Server-Sent Events stream with real-time health updates

Webhooks

Local webhook management.

Base: /webhooks

List Webhooks

GET /webhooks

Auth: Required

Get Webhook by Workflow

GET /webhooks/workflow/:workflowId

Auth: Required

Delete Webhook

DELETE /webhooks/workflow/:workflowId

Auth: Required

Tool Schemas

Tool schema registry and metadata.

Base: /tool-schemas

Get All Schemas

GET /tool-schemas/schemas

Auth: Not required

Response:

{
  "Data & Knowledge": [
    {
      "type": "web_search",
      "name": "Web Search",
      "description": "Search the web",
      "inputSchema": {},
      "outputSchema": {}
    }
  ],
  "Productivity": []
}

Get Schema by Tool Type

GET /tool-schemas/schemas/:toolType

Auth: Not required

Get Schemas by Category

GET /tool-schemas/schemas/category/:category

Auth: Not required

Get Registry Stats

GET /tool-schemas/stats

Auth: Not required

Response:

{
  "totalTools": 45,
  "categories": 6,
  "sources": {
    "builtin": 30,
    "mcp": 15
  }
}

Get Tool Metadata

GET /tool-schemas/metadata/:toolType

Auth: Not required

Reload Registry

POST /tool-schemas/reload

Auth: Not required

Next Steps

• Local API Overview - Overview and setup
• Remote API Reference - Cloud API endpoints
• Authentication Guide - Auth methods
• Examples - Code examples