Manus AI API: Keys, Webhooks and Rate Limits, Step by Step

Manus AI does have a developer API, and the version to build on is v2, because Manus has deprecated v1 and says it will be removed. The model is unusual. You are not calling a chat model; you hand a whole task to the agent, which plans the work and returns finished outputs such as reports, slides, websites or data analyses. The number that shapes every integration is the rate limit: creating a task or sending a message is capped at 10 requests a minute per user, shared across all your keys and identical on every subscription plan. Plan for slow, asynchronous jobs.

What v2 covers before you write a line

The v2 API is RESTful, served from the api.manus.ai base address, and covers tasks, projects, files, webhooks, skills and agents. Every response arrives in the same wrapper with an ok flag, a request ID and, on failure, one of six error codes, from unauthenticated and invalid_argument to rate_limited and internal. Manus publishes an OpenAPI specification as openapi_v2.json. It also ships an official API skill for coding agents, installed with the Skills CLI and carrying no API key, and typing /manus-api inside a Manus task invokes the same skill without installing anything.

Money works differently from a model API. The API docs we read state no API price list and no plan requirement for API keys; the one hard gate is that Open Apps need a Team account. API tasks spend the account's credits like any other task, and Manus cannot estimate a task's credit cost in advance. Over the API it is even blunter: a high-credit data call raises a notice, but the credit amount is not exposed. How the modes and credits behave is covered in our Manus AI playbook. Contractually, the APIs sit under a separate Master Services Agreement with an Order Form, not the consumer Terms.

Step 1: choose a key or an Open App

For your own scripts, an API key is the short route. You send it in the x-manus-api-key header; the alternative is an OAuth2 token in the Authorization Bearer header. Each account can hold up to 50 keys, created in the Developers settings and shown only once. Each key has full access to the account, so a leaked key must be revoked immediately. Rate limits are counted per user and shared across every key you own. More keys add no capacity. Splitting a busy workload across ten keys still hits the same per-minute ceiling.

Open Apps are the OAuth route for software that other people authorize, and they are Team-only: personal accounts can neither create nor authorize them, and only members of the creator's team can grant access. There are three types. A team app is standard OAuth; trusted_team carries the same permissions as an API key and only a Team Owner or Admin can create it; trusted_public is for partners only. The flow is the Authorization Code Grant with PKCE. Codes expire in 10 minutes, access tokens last 24 hours and refresh tokens 30 days, and each app can keep five active secrets for rotation.

Scopes are narrow by design: create_task, manage_all_tasks, create_project, use_connectors and use_my_browsers. A standard OAuth client cannot call the agent, skill upload, webhook or usage endpoints, so anything that registers webhooks needs a key or a trusted client. Upgrading a client to trusted team, or widening its scopes or connectors, invalidates every token already issued. Users must then authorize the app again, so settle scopes before launch.

Step 2: send a task and let it run

A call to task.create returns at once; the work continues in the background. You can poll task.listMessages for status events, but Manus advises webhooks for progress. The agent status moves between running, stopped, waiting and error. Stopped is not always final. If task.detail reports background jobs still running, the task can wake and change its results, and a later message, schedule or trigger can restart the same task. Treat a stop as a checkpoint, not a closed record, until your own logic decides otherwise.

Two kinds of pause need different calls, and mixing them up is the classic bug. When the agent asks a question, you answer with task.sendMessage. When it wants approval for an action, the task enters waiting and you reply with task.confirmAction and the event ID it gave you. Approvals cover Gmail and Outlook sends (send, save as draft or cancel), calendar changes, terminal commands (with an always-allow flag), Shopify product deletions, Instagram publishing and video generation. Sending an ordinary message while an approval is pending silently skips that action.

Two of those approvals are thinner than they look. An Instagram draft goes live only on accept, and the API offers no decline input; to leave it unpublished you resume the task without accepting. Video generation asks for approval without exposing the model, the duration or a credit estimate, and declining simply means no video. The agent can also borrow your local browser: a waiting event asks you to pick an online browser client, and an empty list means the Manus browser extension is not installed or enabled.

For machine-readable results, pass a JSON Schema in structured_output_schema. Extraction is a separate pass that runs only after the task finishes with a finish stop; a later message without a new schema triggers no extraction. The schema must be a strict subset: an object at the root, additionalProperties set to false everywhere, every property listed as required (optional fields use nullable types) and no more than five levels of nesting. Keywords such as pattern, minimum, maxItems and oneOf are rejected with HTTP 400. Each result carries success, value and error fields.

Going over a limit returns HTTP 429 with the rate_limited code ^[1]. The OAuth token and revoke endpoints have their own ceiling of 60 requests a minute per client ID, and the docs advise exponential backoff with jitter. Because the task-creation cap belongs to the user rather than the key, any job that fans out work should queue its creates instead of firing them at once. A polling loop on task.detail also eats into its own allowance quickly. Webhooks avoid that.

Step 3: receive webhooks and verify every one

Manus sends three lifecycle events: task_created, task_stopped (with a stop reason of finish or ask) and task_deleted. You register endpoints in the Developers settings, and Manus sends a test request before a webhook goes live. Your endpoint must accept a JSON POST and return HTTP 200 within 10 seconds. A task_stopped payload can carry attachments with file name, URL and size, plus the structured result if you asked for one. Deletion events fire only for tasks created through the API, and task.list with include_deleted recovers any you missed.

Verification is not optional. Each request is signed with RSA-SHA256 using a 2048-bit key, with the signature and a timestamp in the X-Webhook-Signature and X-Webhook-Timestamp headers ^[2]. The signed string joins three parts with dots: the timestamp, the full webhook URL including query parameters, and the SHA-256 hex digest of the raw body. Fetch the public key from the webhook.publicKey endpoint with your API key and cache it, for example for an hour. Reject anything older than five minutes. Manus may add event types later, so ignore unknown ones but still answer 200.

Publishing websites from code: four endpoints and one trap

Sites the agent builds are managed through website.status, website.listCheckpoints, website.publish and website.update. Each checkpoint is a snapshot backed by a git commit with its own version ID. Publishing always deploys the latest checkpoint, runs asynchronously and cannot pin an older one. To change an existing site, pass a website field with an instruction to task.create; mobile apps and games are not accepted there. Publishing can fail with failed_precondition when the site lacks a membership, configured secrets or publishing settings. Billing for hosting is separate, as our Manus AI website builder guide explains.

The trap is visibility. Publish defaults to public, and a republish that omits the visibility value turns a private or team-only site public again ^[3]. Always send it. The three values are public, team (team accounts only) and private, meaning the owner and invited collaborators. There is no public unpublish endpoint; taking a site down means emailing Manus's API support. Several builder steps are also missing over the API, including GitHub repository setup, connecting Stripe, claiming a Shopify store and choosing the agent mode, and the agent simply continues without them.

When code is more than the job needs

Zapier is the no-code route. Manus connects to more than 8,000 apps through it, with four actions: create, get, update and delete a task. A Zapier-started task can run in Agent, Chat or Adaptive mode and enable connectors, and the integration works on Zapier's free plan. Manus frames the trade plainly: Zapier needs no programming, while the API gives more flexibility and control. For owner-run teams wiring email or forms to Manus, that is often enough, as our guide for small business shows.

Slack offers three ways in: a direct-message agent with memory, @manus tagged in a thread, and a Slack Connector that reads channels and posts as you. Everyone who talks to @manus needs a Manus account, and the AI features inside Slack need a paid Slack plan. For a service missing from the catalog, you can add a custom MCP server by URL or command, or save an API key as a custom API. A custom MCP server must run on infrastructure you control, over HTTPS, and takes real development work. Over the API, connectors are authorized in the web app first, then passed by ID.

The bottom line

The Manus AI API is a task queue for a full agent, not a model endpoint, and it rewards developers who design for that. Build on v2, store keys like passwords because each one opens the whole account, and route personal scripts through keys while saving Open Apps for a Team account. Lean on signed webhooks rather than polling, check the success flag on every structured result, and send visibility on every publish. Budget conservatively, because no endpoint will tell you a task's credit cost before it runs.