> ## 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.
# List tasks
> Workspace member with access to this resource.
Request: Query: `limit?: integer`, `offset?: integer`, `area_id?: UUID`, `creator_id?: UUID`, `status?: string`, `include_closed?: boolean`, `open_only?: boolean`, `metadata?: JSON object`. `status=done` lists completed Tasks; other status values do not filter derived statuses. Default excludes closed Tasks. `include_closed=true` includes them; `open_only=true` bypasses pagination. Limit defaults to 100 and is capped at 100. Retired assignee/label/property filters return 400.
Response: `{tasks:TaskResponse[],total:integer}`.
Status: 200; 400 invalid filters. Authentication and resource-access errors follow [Overview](/api-reference/errors).
## OpenAPI
````yaml /api-reference/openapi.json get /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: >-
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).
Areas operations available within the caller's documented permissions.
- name: Artifacts
description: >-
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).
Artifacts operations available within the caller's documented permissions.
- name: Authentication
description: >-
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).
Authentication operations available within the caller's documented
permissions.
- name: Automations
description: >-
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).
Automations operations available within the caller's documented
permissions.
- name: Companies
description: >-
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).
Companies operations available within the caller's documented permissions.
- name: Execution funding
description: >-
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).
Execution funding operations available within the caller's documented
permissions.
- name: Files
description: >-
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).
Files operations available within the caller's documented permissions.
- name: GitHub
description: >-
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).
GitHub operations available within the caller's documented permissions.
- name: Interactions
description: >-
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).
Interactions operations available within the caller's documented
permissions.
- name: Knowledge
description: >-
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).
Knowledge operations available within the caller's documented permissions.
- name: MCP
description: MCP operations available within the caller's documented permissions.
- name: Messages
description: >-
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).
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: >-
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).
Private network operations available within the caller's documented
permissions.
- name: Runs
description: >-
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).
Runs operations available within the caller's documented permissions.
- name: Skills
description: >-
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).
Skills operations available within the caller's documented permissions.
- name: Tasks
description: >-
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).
Tasks operations available within the caller's documented permissions.
- name: Vault
description: >-
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).
Vault operations available within the caller's documented permissions.
- name: Webhooks
description: >-
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).
Webhooks operations available within the caller's documented permissions.
paths:
/api/tasks:
get:
tags:
- Tasks
summary: List tasks
description: >-
Workspace member with access to this resource.
Request: Query: `limit?: integer`, `offset?: integer`, `area_id?: UUID`,
`creator_id?: UUID`, `status?: string`, `include_closed?: boolean`,
`open_only?: boolean`, `metadata?: JSON object`. `status=done` lists
completed Tasks; other status values do not filter derived statuses.
Default excludes closed Tasks. `include_closed=true` includes them;
`open_only=true` bypasses pagination. Limit defaults to 100 and is
capped at 100. Retired assignee/label/property filters return 400.
Response: `{tasks:TaskResponse[],total:integer}`.
Status: 200; 400 invalid filters. Authentication and resource-access
errors follow [Overview](/api-reference/errors).
operationId: listTasks
parameters:
- name: area_id
in: query
description: Optional area_id filter or control; see the operation contract.
schema:
type: string
- name: creator_id
in: query
description: Optional creator_id filter or control; see the operation contract.
schema:
type: string
- name: exclude_origin_type
in: query
description: >-
Optional exclude_origin_type filter or control; see the operation
contract.
schema:
type: string
- name: include_closed
in: query
description: >-
Optional include_closed filter or control; see the operation
contract.
schema:
type: string
- name: limit
in: query
description: Optional limit filter or control; see the operation contract.
schema:
type: string
- name: metadata
in: query
description: Optional metadata filter or control; see the operation contract.
schema:
type: string
- name: offset
in: query
description: Optional offset filter or control; see the operation contract.
schema:
type: string
- name: open_only
in: query
description: Optional open_only filter or control; see the operation contract.
schema:
type: string
- name: participated_only
in: query
description: >-
Optional participated_only filter or control; see the operation
contract.
schema:
type: string
- name: sort
in: query
description: Optional sort filter or control; see the operation contract.
schema:
type: string
- name: status
in: query
description: Optional status filter or control; see the operation contract.
schema:
type: string
- name: top_level_only
in: query
description: >-
Optional top_level_only filter or control; see the operation
contract.
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
responses:
'200':
description: '`{tasks:TaskResponse[],total:integer}`.'
content:
application/json:
schema:
type: object
properties:
tasks:
type: array
items:
$ref: '#/components/schemas/TaskResponse'
total:
type: integer
required:
- tasks
- total
'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'
'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:
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
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
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.