How to Use the Manus AI API for Agent Tasks

Manus API files are automatically deleted 48 hours after upload, and each file is capped at 512 MB with a 10 GB total storage quota per account. That retention window, documented in the official file.upload reference, is the constraint most overview pages skip. The Manus AI API is useful for creating and managing agent tasks. Production systems also need a plan for where outputs live after the task stops.

According to the Manus API v2 introduction, the API lets you programmatically create and manage AI agent tasks through a REST surface at https://api.manus.ai. You can build automations, orchestrate multi-step work, and integrate Manus into your own apps. API v1 is deprecated and scheduled for removal. New work should target v2 only.

The official v2 surface covers six resource groups:

• Tasks: create work, send follow-ups, list messages, stop or delete tasks
• Projects: group related tasks under shared instructions
• Files: upload attachments for agents to read during a task
• Webhooks: receive push notifications when task state changes
• Skills: list and control which skills an agent may use
• Agents: list and configure custom agents on your account

That definition is narrower than "chat completions." You are not calling a model with a prompt and a token limit. You are starting an agent run that can plan, use tools, attach files, pause for confirmation, and return multi-format results. Manus describes this difference : traditional AI APIs return text, while the Manus API sends a task and expects a complete deliverable.

Search demand for the primary phrase is still early. DataForSEO reports about 70 monthly US searches for "manus ai api" at keyword difficulty 12, which means the documentation is still the main SERP competition. A practical how-to that covers auth, the task lifecycle, and post-task storage can fill a real gap without inventing features.

Every request needs credentials. The authentication docs support two methods.

API key (direct integrations)

1. Open Manus API Integration settings in the Manus web app.
2. Click Create API Key and name it (for example, production or dev-testing).
3. Copy the key immediately. It is shown once.
4. Store it in an environment variable or secrets manager. Never commit it to source control.

Each account can hold up to 50 API keys. Rate limits apply per user and are shared across all of that user's keys. Include the key on every request:

curl -X POST https://api.manus.ai/v2/task.create \
  -H "Content-Type: application/json" \
  -H "x-manus-api-key: $MANUS_API_KEY" \
  -d '{
    "message": {
      "content": "Summarize the attached Q2 pipeline CSV and list open risks."
    }
  }'

OAuth2 bearer token (third-party apps)

For apps that act on behalf of team users, use an OAuth2 access token in the Authorization header:

curl https://api.manus.ai/v2/task.list \
  -H "Authorization: Bearer {access_token}"

OAuth tokens are scoped (for example create_task or manage_all_tasks). Open App creation and authorization require a Team account, and only users in the same team as the app creator can authorize the app. Some endpoints, including webhook management, are API-key only.

Error shape

Missing or invalid credentials return a consistent wrapper:

{
  "ok": false,
  "request_id": "req_abc123",
  "error": {
    "code": "permission_denied",
    "message": "Invalid or missing API key"
  }
}

Keep request_id in your logs. Manus support asks for it when you report failures.

Keep Manus deliverables after the 48-hour window

Park agent outputs in a shared Fast.io workspace with version history, hybrid search, and MCP access for the next run. Every organization starts with a 14-day free trial.

Start 14-Day Trial

The featured path most teams need is short: create a task, attach context files, wait for completion, read the result. Official docs recommend webhooks for production, with polling as a fallback.

1. Create a task

POST https://api.manus.ai/v2/task.create accepts a message object. Content can be a plain string or an array of content parts. A minimal Python call:

import os
import requests

response = requests.post(
    "https://api.manus.ai/v2/task.create",
    headers={
        "Content-Type": "application/json",
        "x-manus-api-key": os.environ["MANUS_API_KEY"],
    },
    json={
        "message": {
            "content": [
                {
                    "type": "text",
                    "text": "Extract action items from the meeting notes PDF.",
                }
            ]
        },
        "title": "Meeting action items",
        "interactive_mode": False,
        "agent_profile": "manus-1.6",
    },
)
data = response.json()
task_id = data["task_id"]
print(data["task_url"])

A successful response includes task_id, task_title, task_url, and optionally share_url when visibility is not private. Useful request fields from the task.create reference:

• project_id: apply a project's shared instructions automatically
• interactive_mode: when true, the agent may pause to ask questions
• hide_in_task_list: hide automated background tasks from the web UI list
• share_visibility: private, team, or public
• agent_profile: manus-1.6, manus-1.6-lite, or manus-1.6-max
• structured_output_schema: JSON Schema for post-run structured extraction
• message.enable_skills / force_skills: control which skills are available or required
• message.connectors: attach external connectors for the run

task.create is rate-limited to 10 requests per minute per user. That limit is shared across all API keys for the account.

2. Attach files

For files up to 512 MB, use the two-step upload flow:

1. Call POST /v2/file.upload with a filename.
2. PUT the bytes to the returned upload_url before it expires (3 minutes).
3. Pass file.id as file_id inside the task message content.

Smaller files can use file_url or base64 file_data, both capped at 20 MB after decoding. Executables and scripts (.exe, .sh, .bat, .dmg, and similar) are rejected.

def upload_file(path: str, api_key: str) -> str:
    import pathlib

filename = pathlib.Path(path).name
    meta = requests.post(
        "https://api.manus.ai/v2/file.upload",
        headers={
            "Content-Type": "application/json",
            "x-manus-api-key": api_key,
        },
        json={"filename": filename},
    ).json()

with open(path, "rb") as f:
        put = requests.put(meta["upload_url"], data=f)
        put.raise_for_status()

return meta["file"]["id"]

Confirm file.status is uploaded via file.detail before you attach the id to a task. Remember the 48-hour deletion clock starts at upload time.

3. Track progress with listMessages or webhooks

Agent work is asynchronous. After task.create, poll:

curl "https://api.manus.ai/v2/task.listMessages?task_id=YOUR_TASK_ID&order=desc&limit=10" \
  -H "x-manus-api-key: $MANUS_API_KEY"

Look for status_update events. The task lifecycle guide defines four agent statuses:

• running: keep waiting
• stopped: task finished; read assistant_message events for results
• waiting: agent needs input or confirmation
• error: inspect error_message

When status is waiting, check waiting_for_event_type. If it is messageAskUser, reply with task.sendMessage. For other waiting types (Gmail send, terminal execute, deploy, calendar actions, and similar), call task.confirmAction with the event id and an input object matching confirm_input_schema.

4. Prefer webhooks in production Register an HTTPS endpoint that returns 2xx:

curl -X POST https://api.manus.ai/v2/webhook.create \
  -H "Content-Type: application/json" \
  -H "x-manus-api-key: $MANUS_API_KEY" \
  -d '{"url": "https://hooks.example.com/manus"}'

Webhook create/list/delete require an API key, not OAuth. Verify signatures with the public key from webhook.publicKey (cache it; it rarely changes). Manus rate-limit guidance is explicit: prefer webhooks over polling, because each task.listMessages poll counts against a 100 requests per minute budget.

5. Retrieve results

When agent_status is stopped, walk the message history for assistant output. If you passed structured_output_schema on create, read the structured extraction result from the lifecycle events. Use task_url when a human needs to inspect the full run in the Manus UI.

The API lifecycle ends when the agent stops. Your product lifecycle usually does not. Competitors' API overviews rarely cover what happens next: durable storage, team review, and ownership transfer from the agent path to a human owner.

Teams commonly try three storage patterns first.

Local disk or the CI runner filesystem works for a one-off script. It fails when the job runs on ephemeral containers, when two services need the same report, or when a reviewer asks for last week's version.

Object storage such as Amazon S3 is durable and cheap at rest. You manage IAM, prefixes, lifecycle rules, and a separate viewer if non-engineers need access. Semantic search and per-file team permissions are not built in, so most teams bolt on extra tools.

Google Drive or similar shared drives are familiar for humans and awkward for high-frequency agent writes. Seat-based pricing and consumer-oriented APIs can slow autonomous loops that write many intermediate files.

A fourth option is a shared intelligent workspace built for agent and human co-use. Fast.io is one such option: org-owned workspaces, per-file version history, granular permissions, append-only audit history, and Intelligence Mode that indexes files for hybrid search once enabled. Agents can talk to Fast.io through a consolidated MCP toolset over Streamable HTTP at /mcp (with legacy SSE at /sse). See the MCP skill docs for the current tool surface.

A practical handoff pattern after Manus completes:

1. Detect agent_status=stopped from a webhook or final poll.
2. Download or serialize the deliverable (report, CSV, slides, website export).
3. Upload into a durable store before the Manus 48-hour file window expires.
4. Notify a human reviewer with a stable link, not a transient Manus attachment id.
5. Optionally transfer workspace ownership so a person owns the org while the agent retains admin for future runs.

Once files sit in a Fast.io workspace with Intelligence enabled, teammates can search by meaning, open collaborative notes next to the artifact, and review the work without hunting through chat history. For document-heavy agent output (contracts, invoices, research PDFs), Metadata Views turn files into a typed, filterable table. That is a separate layer from Intelligence Mode: Metadata Views extract structured fields; Intelligence Mode powers search and chat with citations.

Fast.io organizations run on paid plans (Starter $29/mo, Business $99/mo, Growth $299/mo) with a 14-day free trial that requires a credit card. Treat Fast.io as the coordination layer around Manus, not as a built-in Manus feature.

The rate limits page applies the same per-user ceilings regardless of subscription plan. Limits that matter most for agent pipelines:

• task.create and task.sendMessage: 10 per minute
• task.listMessages, task.detail, task.list: 100 per minute
• file.upload: 40 per minute
• webhook.create: 40 per minute

On 429 responses you get error.code = rate_limited. Back off with exponential delay and jitter. Do not spin tight poll loops against task.listMessages.

Other common error codes from the introduction page:

• invalid_argument: missing or malformed fields
• not_found: bad task, file, or webhook id
• permission_denied: bad key, wrong OAuth scope, or key-only endpoint with a bearer token

Production checklist that maps cleanly to the official docs:

• Target v2 endpoints only. Do not start new work on v1.
• Name API keys by environment and rotate compromised keys immediately.
• Use projects when many tasks share the same standing instructions.
• Set hide_in_task_list for pure automation so the UI stays readable for humans.
• Pass structured_output_schema when a downstream system needs JSON, not prose.
• Verify webhook signatures before acting on events.
• Export artifacts to durable storage before Manus deletes uploaded files at 48 hours.
• Log request_id on every failure path.

What you can build with this surface is broader than a demo chat: scheduled research digests, intake bots that attach customer PDFs, internal tools that force specific skills, Open Apps that create tasks on behalf of teammates, and website-building flows that later call website endpoints once a session has a site attached. The API is the control plane. Your durable workspace is where the deliverable becomes team property.