> ## 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.

# Start task run

> Human workspace member; rejects Run and MCP actors.

Request: Optional top-level `harness:string`, `model:string`, `thinking_level:string`, `service_tier:string` (TaskExecutionRequest). Cannot override `max_attempts`. Requires saved conversation instructions and an idle open Task.

Response: `{run:RunResponse,execution?:TaskExecutionSettings}`.

Status: 202; 400 no instructions/invalid selection; 409 not idle or no target. Authentication and resource-access errors follow [Overview](/api-reference/errors).



## OpenAPI

````yaml /api-reference/openapi.json post /api/tasks/{id}/start
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/{id}/start:
    post:
      tags:
        - Tasks
      summary: Start task run
      description: >-
        Human workspace member; rejects Run and MCP actors.


        Request: Optional top-level `harness:string`, `model:string`,
        `thinking_level:string`, `service_tier:string` (TaskExecutionRequest).
        Cannot override `max_attempts`. Requires saved conversation instructions
        and an idle open Task.


        Response: `{run:RunResponse,execution?:TaskExecutionSettings}`.


        Status: 202; 400 no instructions/invalid selection; 409 not idle or no
        target. Authentication and resource-access errors follow
        [Overview](/api-reference/errors).
      operationId: startTaskRun
      parameters:
        - name: id
          in: path
          required: true
          description: id from the corresponding authorized response.
          schema:
            type: string
        - 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: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/startTaskRunRequestInput'
      responses:
        '202':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/startTaskRunResponse'
        '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: 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'
      security:
        - bearerAuth: []
components:
  schemas:
    startTaskRunRequestInput:
      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'
    startTaskRunResponse:
      type: object
      properties:
        run:
          $ref: '#/components/schemas/RunResponse'
        execution:
          anyOf:
            - $ref: '#/components/schemas/TaskExecutionSettings'
            - type: 'null'
      required:
        - run
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
      required:
        - error
      additionalProperties: true
    RunResponse:
      type: object
      properties:
        access:
          anyOf:
            - $ref: '#/components/schemas/RunAccessReceipt'
            - type: 'null'
        id:
          type: string
        execution_owner_id:
          type: string
        worker_id:
          type: string
        model:
          type: string
        thinking_level:
          type: string
        service_tier:
          type: string
        execution_receipt:
          anyOf:
            - $ref: '#/components/schemas/RunExecutionReceipt'
            - type: 'null'
        task_id:
          type: string
        workspace_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - deferred
            - dispatched
            - running
            - paused
            - completed
            - failed
            - cancelled
          description: >-
            See [Task, Run and fiscal
            states](/concepts/overview#completion-has-several-meanings).
        dispatched_at:
          anyOf:
            - type: string
            - type: 'null'
        started_at:
          anyOf:
            - type: string
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
        result: {}
        error:
          anyOf:
            - type: string
            - type: 'null'
        failure_reason:
          type: string
        attempt:
          type: integer
        max_attempts:
          type: integer
        parent_run_id:
          anyOf:
            - type: string
            - type: 'null'
        created_at:
          type: string
        work_dir:
          type: string
        relative_work_dir:
          type: string
        branch_name:
          type: string
        trigger_message_id:
          anyOf:
            - type: string
            - type: 'null'
        coalesced_message_ids:
          type: array
          items:
            type: string
        delivered_message_ids:
          type: array
          items:
            type: string
        trigger_summary:
          anyOf:
            - type: string
            - type: 'null'
        automation_invocation_id:
          type: string
        interaction_continuation:
          anyOf:
            - $ref: '#/components/schemas/InteractionContinuationData'
            - type: 'null'
        kind:
          type: string
        attribution:
          anyOf:
            - $ref: '#/components/schemas/RunAttribution'
            - type: 'null'
        usage:
          type: array
          items:
            $ref: '#/components/schemas/RunUsageData'
        billed:
          anyOf:
            - $ref: '#/components/schemas/RunBilledUsage'
            - type: 'null'
      required:
        - id
        - execution_owner_id
        - worker_id
        - task_id
        - workspace_id
        - status
        - dispatched_at
        - started_at
        - completed_at
        - result
        - error
        - attempt
        - max_attempts
        - created_at
        - delivered_message_ids
        - kind
    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
    RunAccessReceipt:
      type: object
      properties:
        method:
          type: string
        reason:
          type: string
        account_id:
          type: string
        provider:
          type: string
        label:
          type: string
        email:
          type: string
      required:
        - method
        - reason
    RunExecutionReceipt:
      type: object
      properties:
        harness:
          type: string
        worker_id:
          type: string
        model:
          type: string
        thinking_level:
          type: string
        service_tier:
          type: string
      required:
        - harness
        - model
        - thinking_level
        - service_tier
    InteractionContinuationData:
      type: object
      properties:
        type:
          type: string
        request_id:
          type: string
        source_run_id:
          type: string
        kind:
          type: string
        status:
          type: string
        title:
          type: string
        message:
          type: string
        payload: {}
        response: {}
        audit_text:
          type: string
        response_actor_type:
          type: string
        response_actor_id:
          type: string
        resolved_at:
          type: string
        resume_provider:
          type: string
        resume_session_id:
          type: string
        tool_call_id:
          type: string
        tool_name:
          type: string
        tool_result: {}
      required:
        - type
        - request_id
        - kind
        - status
    RunAttribution:
      type: object
      properties:
        source:
          type: string
        precise:
          type: boolean
        initiator:
          anyOf:
            - $ref: '#/components/schemas/AttributionUser'
            - type: 'null'
        originator:
          anyOf:
            - $ref: '#/components/schemas/AttributionUser'
            - type: 'null'
        evidence:
          anyOf:
            - $ref: '#/components/schemas/RunEvidence'
            - type: 'null'
        automation_version_id:
          type: string
        delegated_from_run_id:
          type: string
        retry_of_run_id:
          type: string
        rerun_of_run_id:
          type: string
      required:
        - source
        - precise
    RunUsageData:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        cache_read_tokens:
          type: integer
        cache_write_tokens:
          type: integer
        cost_usd_ticks:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - model
        - input_tokens
        - output_tokens
        - cache_read_tokens
        - cache_write_tokens
    RunBilledUsage:
      type: object
      properties:
        model_usd_ticks:
          type: string
        estimated:
          type: boolean
      required:
        - model_usd_ticks
        - estimated
    AttributionUser:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        avatar_url:
          type: string
      required:
        - id
    RunEvidence:
      type: object
      properties:
        kind:
          type: string
        ref_id:
          type: string
      required:
        - kind
        - ref_id
  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.