Manus AI Agent

Manus is an autonomous AI agent for long-running, complex tasks. Excels at deep research with parallel processing, web browsing, and comprehensive report generation.

Quick Start

# Create a task
curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Your task description",
    "agentProfile": "manus-1.6"
  }'

# Poll for results (repeat until status != "running")
curl -s "https://api.manus.ai/v1/tasks/{task_id}" \
  -H "API_KEY: $MANUS_API_KEY"

When to Use Manus

Best for (1-10+ minute autonomous work):

• Research: Market analysis, competitive intelligence, fact-checking, stock analysis
• Content: Reports, presentations, videos, websites, visualizations
• Data: PDF translation, multi-source synthesis, analysis with charts
• Development: Chrome extensions, POCs, prototypes, code review
• Automation: Form filling, Web scraping (JS-rendered), task scheduling

Not for (use Claude Code instead):

• Quick web searches or page fetches
• Code generation/editing
• Simple file I/O operations
• Git operations

Core Workflow

Create Task → Get task_id → Poll Status → Extract Results → Done

1. POST /v1/tasks - Create and get task_id
2. GET /v1/tasks/{task_id} - Poll every 5-10 seconds until status ≠ "running"
3. Extract - Read output[].content[].text from completed response

API Reference

Base URL

https://api.manus.ai/v1

Authentication

API_KEY: $MANUS_API_KEY (header)

Create Task

POST /v1/tasks
Content-Type: application/json
API_KEY: $MANUS_API_KEY

{
  "prompt": "Your task description",
  "agentProfile": "manus-1.6",       # manus-1.6-lite | manus-1.6 | manus-1.6-max
  "taskMode": "agent",               # agent | chat | adaptive (optional)
  "projectId": "proj_xxx",           # optional - use project context
  "connectors": ["uuid1"],           # optional - gmail, calendar, notion
  "attachments": [],                  # optional - files, URLs, file_ids
  "hideInTaskList": false,            # optional - hide from task list
  "createShareableLink": false,       # optional - public accessibility
  "taskId": "existing_task_id",       # optional - continue multi-turn conversation
  "locale": "en-US",                  # optional - user locale (e.g. "en-US", "zh-CN")
  "interactiveMode": false            # optional - enable follow-up questions
}

Response:

{
  "task_id": "TeBim6FDQf9peS52xHtAyh",
  "task_title": "Generated Title",
  "task_url": "https://manus.im/app/TeBim6FDQf9peS52xHtAyh",
  "share_url": "https://manus.im/share/xxx"
}

Get Task (Poll for Results)

GET /v1/tasks/{task_id}
API_KEY: $MANUS_API_KEY

Response:

{
  "id": "task_id",
  "status": "running",          # running | completed | failed | stopped
  "model": "manus-1.6-adaptive",
  "metadata": {
    "task_title": "Task Title",
    "task_url": "https://manus.im/app/xxx"
  },
  "output": [
    {
      "role": "assistant",
      "status": "completed",
      "content": [
        {"type": "output_text", "text": "The result text..."}
      ]
    }
  ],
  "credit_usage": 42
}

List All Tasks

GET /v1/tasks
API_KEY: $MANUS_API_KEY

Returns array of all tasks with status, metadata, and credit usage.

Delete Task

DELETE /v1/tasks/{task_id}
API_KEY: $MANUS_API_KEY

Create Project

POST /v1/projects
API_KEY: $MANUS_API_KEY

{
  "name": "Project Name",
  "instruction": "Default instruction for all tasks in this project"
}

List Projects

GET /v1/projects
API_KEY: $MANUS_API_KEY

Upload File (for attachment)

POST /v1/files/upload
API_KEY: $MANUS_API_KEY
Content-Type: multipart/form-data

file: <binary file data>

Returns file_id for use in task attachments. Upload window: 3 minutes.

Create Webhook

POST /v1/webhooks
API_KEY: $MANUS_API_KEY

{
  "url": "https://your-server.com/webhook"
}

Webhook Events:

• task_created - Task started
• task_progress - Task making progress (plan updates)
• task_stopped - Task completed or needs input (stop_reason: "finish" or "ask")

Agent Profiles

Integration Patterns

Simple Task (Standard)

curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze Bitcoin price trends this week",
    "agentProfile": "manus-1.6"
  }'

Complex Research (Max Profile)

curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Deep analysis of AI market 2024-2026: market size, top 10 players, M&A trends, funding landscape",
    "agentProfile": "manus-1.6-max",
    "locale": "en-US"
  }'

With Attachments (URL + Base64 + File ID)

curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze this financial report and create a summary",
    "attachments": [
      {"type": "url", "url": "https://example.com/report.pdf"},
      {"type": "file_id", "file_id": "file_xxx"},
      {"type": "base64", "data": "base64....", "mimeType": "text/csv", "fileName": "data.csv"}
    ],
    "agentProfile": "manus-1.6"
  }'

Multi-turn Conversation

curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Based on your previous analysis, what are the investment implications?",
    "taskId": "abc123",
    "interactiveMode": true
  }'

With Project Context

curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze our Q1 competitor landscape",
    "projectId": "proj_xxx",
    "agentProfile": "manus-1.6"
  }'

With Connectors (Gmail, Calendar, Notion)

curl -X POST "https://api.manus.ai/v1/tasks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Check my calendar for the next 3 months and suggest the best time for a team offsite",
    "connectors": ["google-calendar-uuid"],
    "agentProfile": "manus-1.6"
  }'

Playbook Templates

Pre-optimized prompts for common workflows:

Prompt Tips for Better Results

Good prompt structure:

Task: [Clear objective]
Scope: [Research scope/timeframe]
Sources: [Prefer specific sources if known]
Output Format: [Structured report, bullet points, CSV, etc.]

Example:

{
  "prompt": "Analyze competitors to ChatGPT in the enterprise AI space (2024-2026).
Scope: Market share, pricing, key features, customer segments.
Sources: G2, Gartner, official docs, recent news.
Output: Structured comparison table + strategic positioning analysis.",
  "agentProfile": "manus-1.6-max",
  "locale": "en-US"
}

Best Practices

1. Agent Profiles

   • lite (fast, simple) → Quick lookups, fact checks
   • 1.6 (default) → Most research tasks, balanced
   • 1.6-max → Complex analysis, multi-source deep dives

2. Prompts

   • Be specific: scope, sources, output format
   • Define timeframe if researching recent events
   • Request structured output (tables, bullet points, etc.)

3. Polling

   • Poll every 5-10 seconds for results
   • Most tasks complete in 1-5 minutes
   • Complex research may take 10+ minutes

4. Projects - Organize related tasks with shared instructions (e.g., "Always cite sources")

5. Webhooks - Monitor task events asynchronously instead of polling (production recommended)

6. Attachments - Include PDFs, images, URLs as research context. File uploads have 3-minute window.

7. Locale - Set locale: "zh-CN" for Chinese output, "en-US" for English, etc.

8. Cost - Monitor credit_usage per task. Budget accordingly.

Polling Loop (Python Example)

import requests
import time
import json

API_KEY = "your-manus-api-key"
BASE_URL = "https://api.manus.ai/v1"

# 1. Create task
response = requests.post(
    f"{BASE_URL}/tasks",
    headers={"API_KEY": API_KEY, "Content-Type": "application/json"},
    json={
        "prompt": "Your task description",
        "agentProfile": "manus-1.6"
    }
)
task_id = response.json()["task_id"]
print(f"Task created: {task_id}")

# 2. Poll for completion
max_retries = 120  # 10 minutes with 5s interval
retry = 0

while retry < max_retries:
    result = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers={"API_KEY": API_KEY}
    ).json()

    status = result.get("status")
    print(f"Status: {status}")

    if status == "completed":
        # 3. Extract results
        outputs = result.get("output", [])
        for output in outputs:
            if output.get("role") == "assistant":
                for content in output.get("content", []):
                    if content.get("type") == "output_text":
                        print("\n=== RESULT ===")
                        print(content["text"])
        break
    elif status in ["failed", "stopped"]:
        print(f"Task {status}")
        break

    time.sleep(5)
    retry += 1

if retry == max_retries:
    print("Timeout: Task took too long")

Routing Logic

Use Claude Code (free, instant) for:

• Code generation, editing, refactoring
• File operations (read/write/search)
• Git operations, GitHub PRs
• Web search, simple page fetching
• Memory persistence

Use Manus (costs credits) for:

• Browser automation (JS-rendered sites)
• Form filling, login-required scraping
• PDF/slide/video generation
• OAuth integrations (Gmail, Calendar)
• Multi-hour autonomous research
• Real purchases/bookings

Webhook Server Example

Simple Python webhook receiver:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event = request.json
    event_type = event.get('event_type')

    if event_type == 'task_created':
        print(f"✅ Task started: {event['task_detail']['task_id']}")

    elif event_type == 'task_progress':
        print(f"⏳ Progress: {event['progress_detail']['message']}")

    elif event_type == 'task_stopped':
        detail = event['task_detail']
        if detail['stop_reason'] == 'finish':
            print(f"✓ Completed: {detail['message']}")
            for att in detail.get('attachments', []):
                print(f"  📎 {att['file_name']} ({att['size_bytes']} bytes)")
                print(f"     URL: {att['url']}")
        else:
            print(f"❓ Needs input: {detail['message']}")

    return jsonify({"status": "ok"})

if __name__ == '__main__':
    app.run(port=8080)

Register webhook:

curl -X POST "https://api.manus.ai/v1/webhooks" \
  -H "API_KEY: $MANUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook"
  }'

Error Codes & Solutions

Resources

• API Docs: https://open.manus.ai/docs
• Playbook Gallery: https://manus.im/playbook
• API Settings: https://manus.im/app?show_settings=integrations&app_name=api
• Webhook Setup: https://manus.im/app?show_settings=integrations
• Dashboard: https://manus.im/app