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

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Create task

> Workspace member with access to this resource.

Request: `title?: string` (derived from nonempty input when omitted), `input?: string`, `description?: string|null`, `area_id?: UUID|null`, `parent_task_id?: UUID|null`, `attachment_ids?: UUID[]`, `client_request_id?: UUID`, `allow_duplicate?: boolean`, `callback_url?: HTTPS URL`, `execution?: {harness:string,model?:string,thinking_level?:string,service_tier?:string,max_attempts?:1}`, `start?: boolean` (`false` saves the Task and its input without running it; an autónomo's or an empresa's company otherwise runs input alone on its default execution, and refuses `area_id` or an execution other than that default with 400 `agents_only`), `isolated?: boolean` (default `false`, immutable; see [Isolated Tasks](/concepts/tasks-api#isolated-tasks)), `mcp_servers?: McpServerInput[]` (at most 10, stored before the first Run starts; workspace owners, admins and API keys only; see [Task MCP servers](/concepts/tasks-api#task-mcp-servers)). Execution requires nonempty input. Text fields must not contain NUL characters, and the JSON body is limited to 1 MiB. `origin_type`/`origin_id` are restricted to the authenticated source Run.

Response: TaskResponse with the same derived fields as `GET /api/tasks/{id}`, plus the initial `run_id` when a Run was created. A `client_request_id` replay returns the original Task in its current state and the same `run_id`; see [Idempotency](/api-reference/idempotency). The response never includes `mcp_servers`; read them with `GET /api/tasks/{id}/mcp-servers`.

Status: 201; 400 invalid input (`code: "task_mcp_servers_invalid"` for `mcp_servers`); 403 `code: "task_mcp_servers_forbidden"` when `mcp_servers` come from anyone but a workspace owner, admin or API key, Run tokens included; 413 body over 1 MiB or `mcp_servers` over 64 KiB sealed; 409 duplicate/idempotency/company/callback-secret conflict; 503 webhook signing or, with `mcp_servers`, the Secrets unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).

Creation also accepts `metadata`, `instructions`, `repositories`, and `execution_identity_id`. The execution object accepts `funding_source` and `provider_account_id`; see the request schema and [Task context](/concepts/tasks-api#atomic-task-context). Requested execution funding that is unavailable returns `409` with `error: requested execution funding is unavailable`.



## OpenAPI

````yaml /api-reference/openapi.json post /api/tasks
openapi: 3.1.0
info:
  title: Melso API
  version: '2026-10-12'
  description: >-
    Customer integration contracts for Melso. Agents access is internal or by
    private invitation. Fiscal approval remains in the authenticated app.
  contact:
    name: Melso
    url: https://melso.ai/en
servers:
  - url: https://melso.ai
    description: Production API origin
security: []
tags:
  - name: Areas
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Areas operations available within the caller's documented permissions.
  - name: Artifacts
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Artifacts operations available within the caller's documented permissions.
  - name: Authentication
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Authentication operations available within the caller's documented
      permissions.
  - name: Automations
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Automations operations available within the caller's documented
      permissions.
  - name: Companies
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Companies operations available within the caller's documented permissions.
  - name: Execution funding
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Execution funding operations available within the caller's documented
      permissions.
  - name: Files
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Files operations available within the caller's documented permissions.
  - name: GitHub
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      GitHub operations available within the caller's documented permissions.
  - name: Interactions
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Interactions operations available within the caller's documented
      permissions.
  - name: Knowledge
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Knowledge operations available within the caller's documented permissions.
  - name: MCP
    description: MCP operations available within the caller's documented permissions.
  - name: Messages
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Messages operations available within the caller's documented permissions.
  - name: OAuth
    description: OAuth operations available within the caller's documented permissions.
  - name: Private network
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Private network operations available within the caller's documented
      permissions.
  - name: Runs
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Runs operations available within the caller's documented permissions.
  - name: Skills
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Skills operations available within the caller's documented permissions.
  - name: Tasks
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Tasks operations available within the caller's documented permissions.
  - name: Vault
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Vault operations available within the caller's documented permissions.
  - name: Webhooks
    description: >-
      <Info>Melso Agents is available only internally or by private invitation.
      Agents-specific features require existing access. For the autónomo fiscal
      service, see [Get started](/essentials/quickstart).</Info>


      Webhooks operations available within the caller's documented permissions.
paths:
  /api/tasks:
    post:
      tags:
        - Tasks
      summary: Create task
      description: >-
        Workspace member with access to this resource.


        Request: `title?: string` (derived from nonempty input when omitted),
        `input?: string`, `description?: string|null`, `area_id?: UUID|null`,
        `parent_task_id?: UUID|null`, `attachment_ids?: UUID[]`,
        `client_request_id?: UUID`, `allow_duplicate?: boolean`, `callback_url?:
        HTTPS URL`, `execution?:
        {harness:string,model?:string,thinking_level?:string,service_tier?:string,max_attempts?:1}`,
        `start?: boolean` (`false` saves the Task and its input without running
        it; an autónomo's or an empresa's company otherwise runs input alone on
        its default execution, and refuses `area_id` or an execution other than
        that default with 400 `agents_only`), `isolated?: boolean` (default
        `false`, immutable; see [Isolated
        Tasks](/concepts/tasks-api#isolated-tasks)), `mcp_servers?:
        McpServerInput[]` (at most 10, stored before the first Run starts;
        workspace owners, admins and API keys only; see [Task MCP
        servers](/concepts/tasks-api#task-mcp-servers)). Execution requires
        nonempty input. Text fields must not contain NUL characters, and the
        JSON body is limited to 1 MiB. `origin_type`/`origin_id` are restricted
        to the authenticated source Run.


        Response: TaskResponse with the same derived fields as `GET
        /api/tasks/{id}`, plus the initial `run_id` when a Run was created. A
        `client_request_id` replay returns the original Task in its current
        state and the same `run_id`; see
        [Idempotency](/api-reference/idempotency). The response never includes
        `mcp_servers`; read them with `GET /api/tasks/{id}/mcp-servers`.


        Status: 201; 400 invalid input (`code: "task_mcp_servers_invalid"` for
        `mcp_servers`); 403 `code: "task_mcp_servers_forbidden"` when
        `mcp_servers` come from anyone but a workspace owner, admin or API key,
        Run tokens included; 413 body over 1 MiB or `mcp_servers` over 64 KiB
        sealed; 409 duplicate/idempotency/company/callback-secret conflict; 503
        webhook signing or, with `mcp_servers`, the Secrets unavailable.
        Authentication and resource-access errors follow
        [Overview](/api-reference/errors).


        Creation also accepts `metadata`, `instructions`, `repositories`, and
        `execution_identity_id`. The execution object accepts `funding_source`
        and `provider_account_id`; see the request schema and [Task
        context](/concepts/tasks-api#atomic-task-context). Requested execution
        funding that is unavailable returns `409` with `error: requested
        execution funding is unavailable`.
      operationId: createTask
      parameters:
        - name: X-Workspace-ID
          in: header
          required: false
          description: >-
            Company UUID for a personal token on company-scoped operations. A
            company API key already binds its company.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequestInput'
            example:
              input: Compare the build options.
              execution:
                harness: codex
      responses:
        '201':
          description: >-
            TaskResponse with the same derived fields as `GET /api/tasks/{id}`,
            plus the initial `run_id` when a Run was created. A
            `client_request_id` replay returns the original Task in its current
            state and the same `run_id`; see
            [Idempotency](/api-reference/idempotency). The response never
            includes `mcp_servers`; read them with `GET
            /api/tasks/{id}/mcp-servers`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Credential, company or resource access denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource unavailable to this caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Duplicate Task, conflicting retry payload, company/callback state,
            or requested execution funding is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request failed; see the operation contract for the condition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited; respect Retry-After when present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Request failed; see the operation contract for the condition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateTaskRequestInput:
      type: object
      properties:
        repositories:
          type: array
          items:
            $ref: '#/components/schemas/TaskRepositoryGrantInput'
          maxItems: 20
          description: >-
            At most 20 repository grants, fixed at Task creation. Requires an
            admin company key and an enabled integration broker. Each grant
            names a canonical GitHub HTTPS URL, read or write permission and a
            credential_reference identifying an authorization grant, never a
            token. The broker response must contain token, expires_at and
            permission matching the request. expires_at must be more than 30
            seconds and at most 70 minutes after the exchange validation time.
            This expiry rule applies to the broker response, not to a Task
            creation field.
        metadata:
          type: object
          additionalProperties:
            type:
              - string
              - number
              - boolean
          maxProperties: 50
          propertyNames:
            pattern: ^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$
          description: >-
            A flat map of strings, numbers and booleans with at most 50 keys.
            Keys match ^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$. The encoded create value
            and stored JSONB each have an 8 KiB limit; storage size is checked
            by the server, not by a JSON Schema character limit. Null values,
            arrays and nested objects are rejected.
        instructions:
          type: string
          pattern: "^[^\0]*$"
          description: >-
            Immutable guidance for every Run on the Task. At most 32768 UTF-8
            bytes and no NUL characters. The server checks bytes, not Unicode
            character count. Run credentials cannot configure this field.
        callback_url:
          type: string
        client_request_id:
          type: string
        title:
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
        parent_task_id:
          anyOf:
            - type: string
            - type: 'null'
        area_id:
          anyOf:
            - type: string
            - type: 'null'
        attachment_ids:
          type: array
          items:
            type: string
        origin_type:
          anyOf:
            - type: string
            - type: 'null'
        origin_id:
          anyOf:
            - type: string
            - type: 'null'
        allow_duplicate:
          type: boolean
        execution:
          anyOf:
            - $ref: '#/components/schemas/TaskExecutionRequestInput'
            - type: 'null'
        start:
          anyOf:
            - type: boolean
            - type: 'null'
        input:
          type: string
        isolated:
          type: boolean
        execution_identity_id:
          type: string
        mcp_servers:
          $ref: '#/components/schemas/McpServerInputsInput'
          description: >-
            At most 10 servers with unique, non-reserved names. Each server uses
            exactly one of a remote HTTPS url or a stdio command. headers belong
            to remote servers; args and env belong to stdio servers. The
            encrypted set is limited to 64 KiB; the server rejects a larger
            sealed set with HTTP 413. This encrypted-size limit cannot be
            measured as JSON character count. Header and environment values are
            write-only; GET returns McpServerSummary objects.
    TaskResponse:
      type: object
      properties:
        execution:
          anyOf:
            - $ref: '#/components/schemas/TaskExecutionSettings'
            - type: 'null'
        id:
          type: string
        workspace_id:
          type: string
        number:
          type: integer
        identifier:
          type: string
        title:
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - cancelled
            - done
            - working
            - paused
            - needs_you
            - to_review
            - idle
          description: >-
            See [Task, Run and fiscal
            states](/concepts/overview#completion-has-several-meanings).
        delivered_at:
          anyOf:
            - type: string
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
        cancelled_at:
          anyOf:
            - type: string
            - type: 'null'
        creator_type:
          type: string
        creator_id:
          type: string
        parent_task_id:
          anyOf:
            - type: string
            - type: 'null'
        area_id:
          anyOf:
            - type: string
            - type: 'null'
        created_at:
          type: string
        updated_at:
          type: string
        origin_type:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          type: object
          additionalProperties: {}
        execution_identity_id:
          anyOf:
            - type: string
            - type: 'null'
        isolated:
          type: boolean
        participant_member_ids:
          type: array
          items:
            type: string
        participant_harnesses:
          type: array
          items:
            type: string
        has_pending_interaction:
          type: boolean
        has_active_run:
          type: boolean
        has_paused_run:
          type: boolean
        attention_reason:
          type: string
        failure_reason:
          type: string
        failure_class:
          type: string
        unread:
          type: boolean
        viewer_participated:
          type: boolean
        pull_request:
          anyOf:
            - $ref: '#/components/schemas/TaskPullRequestSummary'
            - type: 'null'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentResponse'
        run_id:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - execution
        - id
        - workspace_id
        - number
        - identifier
        - title
        - description
        - status
        - delivered_at
        - completed_at
        - cancelled_at
        - creator_type
        - creator_id
        - parent_task_id
        - area_id
        - created_at
        - updated_at
        - origin_type
        - metadata
        - isolated
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
      required:
        - error
      additionalProperties: true
    TaskRepositoryGrantInput:
      type: object
      properties:
        url:
          type: string
        ref:
          type: string
        permission:
          type: string
        credential_reference:
          type: string
    TaskExecutionRequestInput:
      type: object
      properties:
        funding_source:
          type: string
        provider_account_id:
          type: string
        harness:
          type: string
        worker_id:
          type: string
        model:
          type: string
        thinking_level:
          type: string
        service_tier:
          type: string
        max_attempts:
          anyOf:
            - type: integer
            - type: 'null'
    McpServerInputsInput:
      type: array
      items:
        $ref: '#/components/schemas/McpServerInputInput'
      maxItems: 10
      description: >-
        At most 10 servers with unique, non-reserved names. Each server uses
        exactly one of a remote HTTPS url or a stdio command. headers belong to
        remote servers; args and env belong to stdio servers. The encrypted set
        is limited to 64 KiB; the server rejects a larger sealed set with HTTP
        413. This encrypted-size limit cannot be measured as JSON character
        count. Header and environment values are write-only; GET returns
        McpServerSummary objects.
    TaskExecutionSettings:
      type: object
      properties:
        version:
          type: string
        harness:
          type: string
        worker_id:
          type: string
        model:
          type: string
        thinking_level:
          type: string
        service_tier:
          type: string
      required:
        - version
        - harness
        - model
        - thinking_level
        - service_tier
    TaskPullRequestSummary:
      type: object
      properties:
        number:
          type: integer
        state:
          type: string
        html_url:
          type: string
        checks_rollup:
          anyOf:
            - type: string
            - type: 'null'
        additions:
          type: integer
        deletions:
          type: integer
        changed_files:
          type: integer
      required:
        - number
        - state
        - html_url
        - additions
        - deletions
        - changed_files
    AttachmentResponse:
      type: object
      properties:
        id:
          type: string
        workspace_id:
          type: string
        task_id:
          anyOf:
            - type: string
            - type: 'null'
        message_id:
          anyOf:
            - type: string
            - type: 'null'
        run_id:
          anyOf:
            - type: string
            - type: 'null'
        uploader_type:
          type: string
        uploader_id:
          type: string
        filename:
          type: string
        url:
          type: string
        download_url:
          type: string
        attachment_download_url:
          type: string
        markdown_url:
          type: string
        content_type:
          type: string
        size_bytes:
          type: integer
        created_at:
          type: string
      required:
        - id
        - workspace_id
        - task_id
        - message_id
        - run_id
        - uploader_type
        - uploader_id
        - filename
        - url
        - download_url
        - markdown_url
        - content_type
        - size_bytes
        - created_at
    McpServerInputInput:
      type: object
      properties:
        name:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,62}$
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
      required:
        - name
      additionalProperties: false
      description: >-
        Remote input: name, url and optional headers. Stdio input: name, command
        and optional args and env. Exactly one nonempty url or command is
        required. Unknown fields are rejected; transport-specific fields are
        validated by the server.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Company API key (mwk_) or personal access token (mel_). A PAT requires
        X-Workspace-ID on company-scoped routes. An API key implies its own
        company.

````

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