> ## Documentation Index
> Fetch the complete documentation index at: https://open.manus.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# task.create

> Creates a new task. The task runs asynchronously. Poll for progress with [task.listMessages](https://open.manus.ai/docs/v2/task.listMessages), send follow-ups with [task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage). See the [Task Lifecycle](https://open.manus.ai/docs/v2/task-lifecycle) guide for the complete flow.

<sup>Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).</sup>

> [!TIP]
>
> **Auth:**
>
> * **API Key:** Full access.
> * **Standard OAuth client:** Requires `create_task` or `manage_all_tasks`. With `create_task`, created tasks are accessible only to the same client; see [Task visibility](https://open.manus.ai/docs/v2/open-app.md#task-visibility).
> * **Trusted client:** Full access.
>
> **Agents:** To message an existing agent instead of creating a new task, use [task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage.md) with `agent-default-main_task` as `task_id`. See the [Agents](https://open.manus.ai/docs/v2/agents-overview.md) guide.
>
> **Websites:** To edit an existing website, set the top-level `website` field next to your instruction. See [Edit a website in a new task](https://open.manus.ai/docs/v2/website.md#edit-a-website-in-a-new-task).


## OpenAPI

````yaml POST /v2/task.create
openapi: 3.1.0
info:
  title: Manus OpenAPI v2
  description: >-
    API for integrating Manus into your workflow. All responses are wrapped with
    {"ok": true, "request_id": "...", ...} for success and {"ok": false,
    "request_id": "...", "error": {"code": "...", "message": "..."}} for errors.
  version: 2.0.0
servers:
  - url: https://api.manus.ai
security:
  - ApiKeyAuth: []
paths:
  /v2/task.create:
    post:
      summary: CreateTask
      description: >-
        Creates a new task. The task runs asynchronously. Poll for progress with
        [task.listMessages](https://open.manus.ai/docs/v2/task.listMessages),
        send follow-ups with
        [task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage). See
        the [Task Lifecycle](https://open.manus.ai/docs/v2/task-lifecycle) guide
        for the complete flow.
      operationId: openapi.v2.OpenapiV2Service.CreateTask
      parameters:
        - name: x-manus-api-key
          in: header
          required: false
          schema:
            type: string
          description: >-
            API key for direct authentication. Provide either this or
            `Authorization`, not both. See
            [Authentication](https://open.manus.ai/docs/v2/authentication).
        - name: Authorization
          in: header
          required: false
          schema:
            type: string
            example: Bearer {access_token}
          description: >-
            OAuth2 access token in `Bearer {token}` format. An OAuth client
            requires the `create_task` or `manage_all_tasks` scope unless it is
            a `Trusted team client` or `Trusted public client`. Provide either
            this or `x-manus-api-key`, not both. See the [Open
            App](https://open.manus.ai/docs/v2/open-app) guide.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  $ref: '#/components/schemas/Message'
                  description: >-
                    The message to start the task with. Contains the prompt
                    text, optional file attachments, and connector/skill
                    configuration.
                website:
                  type: object
                  title: Website
                  description: >-
                    Optional. An existing website for the new task to edit — the
                    same as attaching the website in the Manus app.
                    `message.content` must also contain a non-empty text
                    instruction; a `hidden` text part also counts. Only web
                    websites owned by the authorized user are accepted; mobile
                    apps and games are not. Only task.create has this field:
                    follow-up messages through
                    [task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage)
                    only need the instruction. See [Edit a website in a new
                    task](https://open.manus.ai/docs/v2/website#edit-a-website-in-a-new-task).
                  properties:
                    id:
                      type: string
                      description: >-
                        Website ID — the same `website_id` that the `website.*`
                        endpoints use, as returned by
                        [website.status](https://open.manus.ai/docs/v2/website.status)
                        or
                        [website.publish](https://open.manus.ai/docs/v2/website.publish).
                        Must not have surrounding whitespace. An OAuth client
                        with only the `create_task` scope can use only websites
                        whose source task it created.
                  required:
                    - id
                project_id:
                  type: string
                  description: >-
                    Project ID to associate this task with. The project's
                    instruction will be automatically applied. Use
                    [project.list](https://open.manus.ai/docs/v2/project.list)
                    to get available project IDs.
                locale:
                  type: string
                  description: >-
                    Locale for the task output language (e.g., "en", "zh-CN",
                    "ja"). Defaults to the user's account locale setting.
                interactive_mode:
                  type: boolean
                  description: >-
                    When enabled, the agent may pause and ask follow-up
                    questions if the input is insufficient. When disabled
                    (default), the agent proceeds with best-effort execution
                    without asking.
                  default: false
                hide_in_task_list:
                  type: boolean
                  description: >-
                    When true, the task does not appear in the Manus webapp task
                    list. It remains accessible through the `task_url` in the
                    response.
                  default: false
                share_visibility:
                  type: string
                  enum:
                    - private
                    - team
                    - public
                  description: >-
                    Who can view the task.


                    - `private` (default) — only the task creator.

                    - `team` — all team members.

                    - `public` — anyone with the `share_url`, without
                    authentication.
                  default: private
                agent_profile:
                  type: string
                  anyOf:
                    - enum:
                        - standard
                        - lite
                        - max
                        - max-medium
                        - max-high
                        - max-extra
                        - max-ultra
                    - pattern: >-
                        ^(?:(?:manus-)?[0-9]+(?:\.[0-9]+)+(?:-(?:standard|lite|max(?:-(?:medium|high|extra|ultra))?))?)?$
                  description: >-
                    Agent profile to use for the task. Use the stable values
                    `standard` (default), `lite`, or `max`. For `max`, you can
                    also choose a thinking level with `max-medium`, `max-high`,
                    `max-extra`, or `max-ultra` (deepest reasoning, slowest, and
                    highest credit usage); plain `max` uses the default Max
                    thinking level, currently equivalent to `max-extra`.
                    Versioned aliases such as `1.6-lite`, `2.0-max`,
                    `2.0-max-ultra`, and the legacy `manus-1.6-lite` form are
                    also accepted; the version segment is ignored because model
                    versions are not selected independently. A version without a
                    suffix, such as `1.6` or `manus-1.6`, means `standard`. Omit
                    the field (or pass an empty string) to use `standard`. Free
                    personal accounts are downgraded to `lite` regardless of the
                    requested value.
                  default: standard
                title:
                  type: string
                  description: >-
                    Custom title for the task. If not provided, a title is
                    generated from the input message. If generation times out,
                    `task_title` is the placeholder `generating title...`; fetch
                    `task.detail` later for the updated title.
                async_title:
                  type: boolean
                  description: >-
                    When `true` and `title` is omitted, the task is created
                    without waiting for title generation. `task_title` is the
                    placeholder `generating title...` until the title is ready;
                    fetch `task.detail` later for the updated title. Ignored
                    when `title` is provided.
                  default: false
                structured_output_schema:
                  type: object
                  description: >-
                    JSON Schema for structured output extraction. When provided,
                    the agent runs normally, then a post-processing step
                    extracts a result conforming to your schema. The schema must
                    follow the [Structured
                    Output](https://open.manus.ai/docs/v2/structured-output)
                    subset of JSON Schema: all object properties must be listed
                    in `required`, and `additionalProperties` must be `false`.
                    See the [Structured
                    Output](https://open.manus.ai/docs/v2/structured-output)
                    guide.
                clear_connectors:
                  type: boolean
                  description: >-
                    Clears the connector selection for the new task. The task
                    starts without connectors; the project's default connectors
                    and your default connectors are not loaded. Cannot be
                    combined with a non-empty `message.connectors`. Other task
                    features may still provide tools. See the
                    [Connectors](https://open.manus.ai/docs/v2/connectors)
                    guide.
                  default: false
              required:
                - message
      responses:
        '200':
          description: Task created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                    description: Whether the request was successful.
                  request_id:
                    type: string
                    description: >-
                      Unique identifier for this API request, useful for
                      debugging.
                  task_id:
                    type: string
                    description: >-
                      Unique identifier for the created task. Use this to track,
                      update, or delete the task.
                  task_title:
                    type: string
                    description: >-
                      Title for the task. Returns the custom title if one was
                      provided in the request, otherwise the generated title, or
                      the placeholder `generating title...` until the title is
                      ready. See `title`.
                  task_url:
                    type: string
                    description: >-
                      URL to view the task in the Manus webapp (e.g.,
                      https://manus.im/app/{task_id}).
                  share_url:
                    type: string
                    description: >-
                      Publicly accessible URL for sharing. Only present when
                      share_visibility is not "private".
                  share_visibility:
                    type: string
                    enum:
                      - private
                      - team
                      - public
                    description: The actual visibility state of the task.
        4XX:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
components:
  schemas:
    Message:
      type: object
      description: A message to send to a task.
      properties:
        content:
          description: >-
            String (plain text) or array of ContentPart objects. User text is
            limited to approximately 5,000 estimated tokens per request; the
            exact character count varies by language and content. For an array,
            the limit applies to the combined text of all text parts; file parts
            do not count. Input over the limit returns InvalidArgument (HTTP
            400). Each message must contain at least one non-empty visible text
            part or valid visible file/voice part.
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
            - type: string
        connectors:
          type: array
          items:
            type: string
          description: >-
            Connector IDs for this task. A non-empty list replaces the task's
            connector selection. An empty array is treated the same as omitting
            the field. When omitted:


            - On `task.create` with `project_id`, the task uses the project's
            default connectors.

            - On `task.create` without `project_id`, the task uses the
            connectors you enabled by default in your account. Connectors that
            are installed but not enabled are not loaded.

            - On `task.sendMessage`, the task keeps its current selection.


            To start or continue without connectors, set the top-level
            `clear_connectors: true`. Use
            [connector.list](https://open.manus.ai/docs/v2/connector.list) to
            get connector IDs.
        enable_skills:
          type: array
          items:
            type: string
          description: >-
            Skill IDs to enable for this task. Use
            [skill.list](https://open.manus.ai/docs/v2/skill.list) to retrieve
            available skill IDs. An empty list is treated the same as omitting
            this field.


            - **API Key:** The user's enabled skills are loaded by default.

            - **Standard OAuth client:** All App-owned skills are loaded by
            default, and user skills are not loaded. When a non-empty list is
            supplied, every ID must be App-owned; the request is rejected
            otherwise.

            - **Trusted client:** The user's enabled skills are loaded by
            default. The client's App skills are always added. IDs of another
            App's skills are rejected.
        force_skills:
          type: array
          items:
            type: string
          description: >-
            Skill IDs the agent must invoke during this task. Forced skills are
            automatically available even if not listed in `enable_skills`.
            Standard OAuth clients can force only App-owned IDs, and Trusted
            clients cannot force another App's skills; the request is rejected
            otherwise.
        task_references:
          type: array
          items:
            type: string
            pattern: ^[A-Za-z0-9]{22}$
          maxItems: 20
          description: >-
            IDs of existing tasks the agent can browse on demand.


            - Bare 22-character task IDs only; up to 20 per request.

            - On task.sendMessage, IDs are added to the task's existing
            references and cannot be cleared.


            See the [Task
            references](https://open.manus.ai/docs/v2/task-references) guide.
      required:
        - content
    ErrorResponse:
      type: object
      description: Standard error response format returned when a request fails.
      properties:
        ok:
          type: boolean
          example: false
          description: Always false for error responses.
        request_id:
          type: string
          description: >-
            Unique identifier for this API request, useful for debugging with
            support.
        error:
          type: object
          description: Error details.
          properties:
            code:
              type: string
              description: >-
                Machine-readable error code (e.g., "invalid_argument",
                "not_found", "permission_denied", "rate_limited").
            message:
              type: string
              description: Human-readable error description explaining what went wrong.
    ContentPart:
      oneOf:
        - type: object
          title: Text
          properties:
            type:
              type: string
              enum:
                - text
              description: Must be "text".
            text:
              type: string
              description: >-
                The text content of the message. Across a ContentPart array, all
                text parts must contain no more than approximately 5,000
                estimated tokens in total.
            visibility:
              type: string
              enum:
                - visible
                - hidden
              default: visible
              description: >-
                Optional. Most integrations can omit this field. A `Trusted
                public client` can set it to `hidden` to pass additional
                application context without displaying it to users. See [Hidden
                application
                context](https://open.manus.ai/docs/v2/hidden-application-context).
          required:
            - type
            - text
        - type: object
          title: File
          description: '**Provide the file via one of: file_id, file_url, or file_data.**'
          properties:
            type:
              type: string
              enum:
                - file
              description: Must be "file".
            file_id:
              type: string
              description: >-
                ID of a file uploaded with
                [file.upload](https://open.manus.ai/docs/v2/file.upload). Up to
                512 MB per file; see
                [Limits](https://open.manus.ai/docs/v2/file.upload#limits).
            file_url:
              type: string
              description: >-
                Publicly accessible URL to the file. Manus downloads it
                directly. Up to 20 MB.
            file_data:
              type: string
              description: >-
                Base64 encoded file content in the form
                `data:<mime_type>;base64,<encoded_content>`. Up to 20 MB after
                decoding.
            filename:
              type: string
              description: >-
                Display name of the file including extension (e.g.,
                "report.pdf"). Required when using file_data; recommended for
                file_url.
            mime_type:
              type: string
              description: >-
                MIME type of the file (e.g., "application/pdf", "image/png").
                Optional; auto-detected from filename if omitted.
            visibility:
              type: string
              enum:
                - visible
              default: visible
              description: >-
                Optional. Most integrations can omit this field. Only `visible`
                is supported for this content type.
          required:
            - type
        - type: object
          title: Voice
          description: '**Provide the audio via one of: file_id, file_url, or file_data.**'
          properties:
            type:
              type: string
              enum:
                - voice
              description: Must be "voice".
            file_id:
              type: string
              description: >-
                ID of an audio file uploaded with
                [file.upload](https://open.manus.ai/docs/v2/file.upload). Up to
                512 MB per file; see
                [Limits](https://open.manus.ai/docs/v2/file.upload#limits).
            file_url:
              type: string
              description: >-
                Publicly accessible URL to the audio file. Manus downloads and
                transcribes it. Up to 20 MB.
            file_data:
              type: string
              description: >-
                Base64 encoded audio content in the form
                `data:<mime_type>;base64,<encoded_content>`. Up to 20 MB after
                decoding.
            filename:
              type: string
              description: >-
                Display name of the audio file including extension (e.g.,
                "recording.wav"). Required when using file_data.
            mime_type:
              type: string
              description: >-
                MIME type of the audio file (e.g., "audio/wav", "audio/mp3").
                Optional; auto-detected from filename if omitted.
            visibility:
              type: string
              enum:
                - visible
              default: visible
              description: >-
                Optional. Most integrations can omit this field. Only `visible`
                is supported for this content type.
          required:
            - type
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-manus-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.