API Service

External API Documentation (v1.0)

Welcome to our External API. This API lets you programmatically interact with our Agent and Task systems to integrate powerful automation and intelligence into your own applications.

Basics

API Base Path

All API requests are prefixed with:

/api/external

API Version

Current API version is 1.0. All responses include header X-API-Version: 1.0.

Authentication

All requests to the external API require an API key.

Obtain an API Key: Log into our web app, go to your user settings, and create a new API key under API Key Management.
Use the API Key: Include header X-API-Key with your key in every request.

Example Request Headers:

GET /api/external/agents HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-API-Key: YOUR_API_KEY_HERE

Common Endpoints

Health Check

Check the API service status.

URL: /health
Method: GET
Success (200 OK):

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2023-10-27T10:00:00.000Z",
    "version": "1.0",
    "service": "mcp-server-external-api"
  }
}

API Info

Get basic information about the API.

URL: /info
Method: GET
Success (200 OK):

{
  "success": true,
  "data": {
    "name": "MCP Server External API",
    "version": "1.0",
    "description": "External API for MCP Server Agent execution and management",
    "endpoints": {
      "agents": "/api/external/agents",
      "tasks": "/api/external/tasks"
    }
  }
}

Agent API

Agent API provides a high-level interface to execute pre-configured automation workflows.

List Agents

URL: /agents
Method: GET
Query Params:
- page (optional): Page number, default 1.
- limit (optional): Items per page, default 20, max 100.
- category (optional): Filter by category.
Success (200 OK):

{
  "success": true,
  "data": {
    "agents": [ /* List of Agent objects */ ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 5,
      "totalPages": 1
    }
  }
}

Get Agent Details

URL: /agents/:agentId
Method: GET
Success (200 OK):

{
  "success": true,
  "data": {
    "agent": { /* Agent details */ }
  }
}

Execute Agent (Non-Streaming)

Execute an Agent and return the result when completed.

URL: /agents/:agentId/execute
Method: POST
Request Body:

{
  "input": "I need a market analysis report on the latest AI trends.",
  "parameters": { "format": "pdf", "lang": "en" },
  "timeout": 180
}

input (string, required): The main instruction for the task.
parameters (object, optional): Extra parameters passed to the Agent.
timeout (number, optional): Timeout in seconds, default 120, max 300.
Success (200 OK):

{
  "success": true,
  "data": {
    "taskId": "...",
    "agentId": "...",
    "result": { /* Execution result */ },
    "status": "completed"
  }
}

Execute Agent (Streaming)

Execute an Agent and receive real-time output via Server-Sent Events (SSE).

URL: /agents/:agentId/execute/stream
Method: POST
Request Body: Same as non-streaming.
Response: text/event-stream

SSE Event Flow:

connection_established: Connection confirmed.

{
  "event": "connection_established",
  "data": {
    "executionId": "external-agent-exec-xxxx",
    "agentId": "...",
    "agentName": "...",
    "input": "...",
    "status": "connected"
  }
}

task_created: Internal task created for the Agent execution.

{
  "event": "task_created",
  "data": { 
    "taskId": "...", 
    "title": "Agent execution: ..."
  }
}

General streaming data: Various events forwarded by the Agent intelligent engine (agentIntelligentService) reflecting real-time progress.
execution_complete: Execution finished.

{
  "event": "execution_complete",
  "data": {
    "taskId": "...",
    "agentId": "...",
    "success": true,
    "executionTime": 5432,
    "result": { /* Final result */ },
    "status": "completed"
  }
}

cancelled: Emitted if the execution is cancelled.
error: Emitted if an error occurs.

Cancel Agent Execution

URL: /agents/:agentId/cancel/:executionId
Method: POST
Note: executionId comes from the connection_established event when streaming.
Success (200 OK):

{
  "success": true,
  "data": {
    "executionId": "...",
    "cancelled": true
  }
}

Chat with Agent

URL: /agents/:agentId/chat
Method: POST
Request Body:

{
  "message": "Hello, what can you do?",
  "conversationId": "..." 
}

conversationId (string, optional): Continue within an existing conversation if provided.
Success (200 OK):

{
  "success": true,
  "data": {
    "conversationId": "...",
    "response": { /* Agent response */ }
  }
}

Create Agent from Task

URL: /agents
Method: POST
Request Body:

{
  "taskId": "...",
  "name": "Market Report Assistant",
  "description": "An agent that generates market analysis reports automatically."
}

Success (201 Created):

{
  "success": true,
  "data": {
    "agent": { /* Newly created Agent object */ }
  }
}

Task API

Task API provides fine-grained control to create, analyze, and execute tasks step by step.

List Tasks

URL: /tasks
Method: GET
Query Params:
- page (optional): Page number.
- limit (optional): Items per page.
- status (optional): Filter by status (pending, running, completed, failed).

Get Task Details

URL: /tasks/:taskId
Method: GET

Create Task

URL: /tasks
Method: POST
Request Body:

{
  "title": "Generate quarterly sales report",
  "content": "Please generate a detailed PDF sales report based on last quarter's data."
}

Success (201 Created):

{
  "success": true,
  "data": {
    "task": { /* Newly created Task object */ }
  }
}

Analyze Task

Task analysis must be performed before execution. This step generates an execution plan and identifies required tools (MCPs).

URL: /tasks/:taskId/analyze
Method: POST
Success (200 OK):

{
  "success": true,
  "data": {
    "task": { /* Updated Task with workflow */ },
    "recommendedMCPs": [ /* Recommended tools */ ],
    "message": "Task analyzed successfully. Please authenticate required MCPs before execution."
  }
}

Execute Task (Non-Streaming)

URL: /tasks/:taskId/execute
Method: POST
Request Body (optional):

{
  "timeoutSeconds": 600
}

timeoutSeconds (number, optional): Execution timeout in seconds, default 600 (10 minutes).
Note: Must be called after /analyze.
Success (200 OK):

{
  "success": true,
  "data": {
    "taskId": "...",
    "title": "...",
    "content": "...",
    "result": { /* Execution result */ },
    "executionTime": 5.2,
    "status": "completed"
  }
}

Execute Task (Streaming)

URL: /tasks/:taskId/execute/stream
Method: POST
Request Body (optional):

{
  "timeoutSeconds": 600
}

Response: text/event-stream

SSE Event Flow:

connection_established: Connection confirmed.

{
  "event": "connection_established",
  "data": {
    "taskId": "...",
    "status": "connected",
    "executionId": "external-task-xxxx"
  }
}

General streaming data: Events forwarded by the task executor (taskExecutorService) such as task_progress and final_result.
completed: Task execution finished.

{
  "event": "completed",
  "data": {
    "taskId": "...",
    "success": true,
    "message": "Task executed successfully"
  }
}

cancelled: Emitted if the execution is cancelled.
error: Emitted if an error occurs.

Cancel Task Execution

URL: /tasks/:taskId/cancel/:executionId
Method: POST

Get Task Execution History

URL: /tasks/:taskId/executions
Method: GET
Success (200 OK):

{
  "success": true,
  "data": {
    "taskId": "...",
    "executions": [ /* List of execution steps */ ]
  }
}

Error Handling

Standard HTTP status codes are used to indicate success or failure.

400 Bad Request: Invalid request parameters.
401 Unauthorized: Invalid or missing API key.
404 Not Found: Resource not found.
408 Request Timeout: Task execution timed out.
500 Internal Server Error: Internal server error.

Error Response Example:

{
  "success": false,
  "error": "INVALID_REQUEST",
  "message": "Invalid request parameters",
  "details": [ /* Detailed error info */ ]
}

Rate Limiting

To ensure service quality, API calls are rate limited. The exact limits depend on your API key configuration. When exceeded, you will receive 429 Too Many Requests.

Usage Examples

Below is a complete example flow for the Task API:

1. Create a Task

curl 'https://your-domain.com/api/external/tasks' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "title": "View Twitter posts",
    "content": "Please fetch my latest tweets"
  }'

2. Analyze the Task

curl 'https://your-domain.com/api/external/tasks/TASK_ID/analyze' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

3. Execute the Task

curl 'https://your-domain.com/api/external/tasks/TASK_ID/execute' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "timeoutSeconds": 600
  }'

4. Streaming Execution (optional)

curl 'https://your-domain.com/api/external/tasks/TASK_ID/execute/stream' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Accept: text/event-stream' \
  -d '{}'

PreviousMCP Overview NextMCP Workflow Builder

Last updated 4 days ago