Manus API Integration Guide

Use this skill when building or troubleshooting integrations that call the Manus API, automate Manus agents, retrieve generated results, manage projects/files/webhooks/connectors/agents/usage, request structured JSON outputs, publish or edit websites created by Manus tasks, or implement OAuth2 authorization for third-party apps.

This file is the routing and decision guide. Keep implementation details in the live official documentation under https://open.manus.ai/docs/. When a user asks for exact request bodies, response schemas, validation rules, rate limits, or endpoint-specific edge cases, open the relevant API v2 page instead of relying on this overview.

Version policy. Use API v2 for all new work. Use the API v1 documentation only when the user is maintaining an existing v1 integration, because v1 is deprecated.

Base URL and authentication. Send requests to https://api.manus.ai. Use x-manus-api-key: <key> for your own integrations and scripts, or Authorization: Bearer <access_token> for an Open App acting on behalf of a user. Successful responses use an ok: true envelope; failures use ok: false with error.code, error.message, and request_id. Standard OAuth tokens are scoped and cannot access full-access-only endpoints. Tokens issued to a Trusted team client or Trusted public client bypass scope restrictions. Open the endpoint page to confirm its supported authentication methods.

---

1. Documentation Routing

Prefer reading the smallest relevant document before answering detailed implementation questions. For endpoint-specific parameters, open https://open.manus.ai/docs/v2/<endpoint>; for the full schema, inspect the API v2 OpenAPI specification. For task skill selection, read the Message.enable_skills and Message.force_skills field descriptions in that schema.

---

2. Endpoint Map

Use this map for orientation only. Open the endpoint page for concrete request and response details.

---

3. Core Integration Decisions

Choose the right authentication method. Use an API key for first-party integrations and scripts. Use OAuth2 when building an Open App that acts on behalf of users. Standard team clients are restricted by configured scopes: create_task, manage_all_tasks, create_project, use_connectors, and use_my_browsers. The create_task scope only exposes tasks created by the same client. project.detail and project.update require manage_all_tasks; create_project covers only project.create and project.list. Standard OAuth tokens can call skill.list and skill.detail with create_task or manage_all_tasks. They cannot access agent.*, webhook.create, webhook.list, webhook.delete, or usage.*, but can access user.me, webhook.publicKey, and website.* without an endpoint-specific scope. A Trusted team client or Trusted public client bypasses standard endpoint scope restrictions like an API key. Hidden text content is an additional Trusted public client capability. Open App creation and standard authorization require a Team account. Trusted public client access is partner-only. Read the Open App guide before implementing OAuth2.

Limit skill discovery by caller. skill.list returns only skills owned by the current Open App for standard OAuth clients. API Keys receive the user's available skills; trusted OAuth clients also receive their App skills. Only API Keys and trusted OAuth clients can pass project_id. Listing a skill does not enable it. Read the skill.list guide for the exact response scope. skill.detail returns one skill's metadata and a 24-hour download link for its current archive. Standard OAuth clients can read only their App's skills, as with skill.list; API Keys and trusted clients can read any skill the user can download. Read the skill.detail guide for the response fields.

Resolve the authenticated user through the API. Call user.me after OAuth token exchange when the integration needs the stable Manus user ID. API Key and Trusted client callers also receive the user's display name, email, and avatar; Standard OAuth clients receive only user_id. Do not parse undocumented claims from the access token. The endpoint accepts API keys and OAuth tokens without an additional OAuth scope, and it does not modify user data.

Choose the right task flow. For a new independent job, call task.create. For an ongoing thread or conversation, store the task_id and call task.sendMessage on later turns. For direct messaging to the default IM agent, task.sendMessage supports the shortcut task_id: "agent-default-main_task".

Use projects for durable behavior. If the integration needs a persistent persona, formatting rule, or reusable instruction, create or reuse a Project and pass project_id when creating tasks. Do not duplicate large system-style instructions into every user message if a project is the cleaner abstraction. To change an existing project, read it with project.detail and send only the changed fields to project.update; connector_ids and skill_ids replace the entire list.

Use webhooks for production result delivery. Polling task.listMessages is acceptable for scripts and prototypes, but production systems should prefer webhooks and verify signatures with the webhook public key. Still implement idempotency and retries because webhook delivery can be repeated by clients or infrastructure. Route by event_type and ignore unknown types. task_deleted reports deletions of API-created tasks; to reconcile missed events, call task.list with include_deleted=true, which returns deleted tasks as status: "deleted" with deleted_at and no title.

Read results on stopped, and keep polling while task.detail.has_running_background_jobs is true. It means a background process may wake the task again later, add messages, and change the results. Read the Task lifecycle guide for details.

Handle waiting states correctly. If the agent asks the user a normal question, answer with task.sendMessage. For action confirmation, read waiting_for_event_id and confirm_input_schema. Fetch a missing tool target with task.listMessages using verbose=true and start_event_id=waiting_for_event_id, then review its tool_used.params and optional tool_used.result. Build the confirmation input according to the schema and submit it through task.confirmAction. Configuration and OAuth targets are not tool targets; do not use the start-event lookup for them because it returns Event not found. confirmed: false means the input was not consumed and the task remains waiting. Fallback when status_detail or waiting_for_event_id is missing, the event type is not one you handle, or the target gives you nothing to act on: call task.sendMessage with message.content set to Continue and use your best judgment. (for most action confirmations this skips the pending action; the agent decides how to proceed), or direct a person to open the task in Manus. Do not invent confirmation input. Read Task lifecycle and task.confirmAction before automating confirmations.

Pick agent profile intentionally. task.create and task.sendMessage accept the stable agent_profile values standard, lite, and max, plus max-medium, max-high, max-extra, and max-ultra to choose a Max thinking level; deeper levels use more credits. Omitting the field on task.create defaults to standard; omitting it on task.sendMessage keeps the task's current profile and thinking level, while passing a value overrides the current and subsequent turns. Versioned profile names are compatibility aliases, not independent model selections. Use the endpoint docs for their accepted format.

Attach tools through message fields. Use message.connectors for connector IDs, message.enable_skills to control available skills, and message.force_skills when a skill must be invoked. Use connector.list and skill.list to discover IDs.

Download uploaded attachments through file.detail. After uploading bytes, use this endpoint to obtain a temporary GET link for content validation before creating a task. Download fields are optional. Links expire; read file.detail for availability and refresh rules.

Follow artifact pagination until has_more is false. Keep the user, credential scope, filters, and page size unchanged. Short or empty pages can still have a next cursor; retry transient failures with the same cursor. The server deduplicates IDs and Addon resources across one traversal. Apply a cursor replay as a replacement for that page. Cursors expire after 5 minutes idle or 15 minutes total; restart on an expired cursor. Deduplicate by resource_uri when present, otherwise by id, when merging separate traversals. Use the returned type for classification; do not infer it from the filename or platform. Read Artifacts guide for categories and live-list semantics.

Respect artifact source visibility. Sources identify the creation task rather than the latest editor. A missing source does not imply UI creation. Credential-filtered lists may omit older artifacts without indexed source metadata. Restricted create_task OAuth clients always have an implicit filter for their own app; omitting source filters cannot recover those historical artifacts. Historical source metadata is not backfilled as part of this release.

Resolve output attachments from message context. task.listMessages returns original message content without rewriting file paths or Manus protocols. Render HTTP/HTTPS normally. Match file destinations to attachments[].path, and resolve manus-webdev://<version_id> through website.listCheckpoints for the same task. If the required context is absent or another non-HTTP protocol is unsupported, remove that link or image node in the client while preserving surrounding text. See Attachments.

Reference existing tasks to reuse prior work. Pass message.task_references (task IDs) on task.create or task.sendMessage so the agent can browse those tasks' conversation and files on demand instead of you re-sending their content. References accumulate across turns and cannot be cleared. Access is checked when the agent reads, except that a create_task-scope OAuth client may reference only its own tasks. Read Task references for validation rules and limits.

Edit an existing website in a new task. Set the top-level website field ({"id": "<website_id>"}) on task.create and put a non-empty text instruction in message.content; the new task edits that website. Only task.create has this field, website is not a content part, and only web websites owned by the authorized user are accepted (not mobile apps or games). Read the Website guide for the rules and errors.

Open a sandbox preview only while it is running. website.status with task_id returns preview_url and sandbox_status. preview_url responds only while sandbox_status is running; it is temporary, so do not store or share it. To bring back a paused preview, send a message with task.sendMessage (requires permission to send messages to the task; runs the agent and consumes credits), then poll website.status with an upper bound. Read the Website guide.

Hidden context requires a Trusted public client. Only text parts may use visibility: "hidden", and every create/send message must retain a valid visible part. User-facing history omits hidden text; a Trusted public client with task access can read it through task.listMessages?verbose=true. See Hidden application context for the contract.

---

4. Structured Output Guidance

Use Structured Output when the integration needs machine-parseable JSON rather than human-facing prose. Before writing schemas or code, read the Structured output guide.

Remember only the routing-level behavior here: pass structured_output_schema to task.create or task.sendMessage; extraction runs after the agent finishes; schemas are arm once, fire once and can be re-armed on later turns; results appear in task.listMessages as structured_output_result or in webhooks as task_stopped.task_detail.structured_output. Always check success before trusting value.

---

5. Operational Limits

Confirm limits in the relevant endpoint page before relying on them because they may change.

• User text is limited to approximately 5,000 estimated tokens per request. This applies to v1 task prompts, OpenAI-compatible Responses input, and v2 task.create / task.sendMessage; multipart input is estimated across all text parts combined, while file parts do not count.
• file.upload accepts files up to 512 MB and enforces 10 GB total storage per account. Exceeding either limit returns QuotaExceededError. Its upload URL expires after 3 minutes, uploaded files are deleted after 48 hours, and executable or script file types are prohibited.
• A task attachment using file_id inherits the file.upload limit. Direct file_url and decoded file_data attachments are limited to 20 MB; 20 MB of decoded data is approximately 26.7 MB of base64 text. There is no hard limit on the number of attachments per message.
• message.task_references accepts up to 20 task IDs per request on task.create and task.sendMessage; entries must be bare 22-character task IDs (a full task URL or the agent-default-main_task shortcut is rejected with InvalidArgument), and the cap is checked before duplicates are removed. References accumulate across turns; a task that accumulates more than 20 keeps the 20 most recently referenced.

---

6. Minimal Implementation Pattern

A typical closed-loop integration follows this sequence: upload files if needed with file.upload; create or reuse a project for durable instructions; call task.create; deliver results through webhooks or poll task.listMessages; continue with task.sendMessage if the conversation needs another turn; and use task.confirmAction only for explicit action confirmations.

For structured-output tasks, add a post-task step that reads either the structured_output_result event or the webhook structured_output field.

---

References

Open these live pages for authoritative details: