AppMage
Home TaskRpc

Task Management

This endpoint group provides functionalities for managing tasks, including creation, retrieval, updating, deletion, and adding comments within specific task instances.

Endpoints

POST /api/rpc (Method: TaskRpc.getData)

  • Description: Retrieves a paginated list of tasks for a given task instance.

  • Request Body:

    {
  "method": "TaskRpc.getData",
  "params": {
    "taskInstanceId": "string",
    "filter": {},
    "sort": {},
    "page": 1,
    "pageSize": 50
  }
}

  • Parameters:

    Name Type Required Description
    taskInstanceId String Yes The ID of the task instance to retrieve tasks from.
    filter Object No An optional object to filter the tasks (e.g., {"status": "todo"}). Defaults to {}.
    sort Object No An optional object to define the sorting order (e.g., {"createdAt": -1}). Defaults to {}.
    page Number No The page number for pagination. Must be a positive integer. Defaults to 1.
    pageSize Number No The number of tasks per page. Must be a positive integer. Defaults to 50.

  • Response:

    {
  "success": true,
  "data": {
    "data": [
      {
        "_id": "string",
        "taskInstanceId": "string",
        "title": "string",
        "description": "string | null",
        "status": "todo | in_progress | in_review | done | blocked",
        "priority": "low | medium | high | urgent",
        "assignees": ["string"],
        "parentId": "string | null",
        "dueDate": "Date | null",
        "completedAt": "Date | null",
        "createdAt": "Date",
        "updatedAt": "Date",
        "tags": ["string"],
        "comments": [
          {
            "commentId": "string (UUID)",
            "authorContactId": "string",
            "content": "string",
            "createdAt": "Date",
            "updatedAt": "Date | null"
          }
        ],
        "isArchived": "boolean"
      }
    ],
    "totalCount": "number"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.getData",
    "params": {
      "taskInstanceId": "654321098765432109876543",
      "page": 1,
      "pageSize": 10,
      "filter": { "status": "todo" }
    }
  }'

POST /api/rpc (Method: TaskRpc.create)

  • Description: Creates a new task within a specific task instance.

  • Request Body:

    {
  "method": "TaskRpc.create",
  "params": {
    "taskInstanceId": "string",
    "title": "string",
    "description": "string | null",
    "status": "todo | in_progress | in_review | done | blocked",
    "priority": "low | medium | high | urgent",
    "assignees": ["string"],
    "parentId": "string | null",
    "dueDate": "Date | null",
    "completedAt": "Date | null",
    "tags": ["string"],
    "comments": [
      {
        "commentId": "string (UUID)",
        "authorContactId": "string",
        "content": "string",
        "createdAt": "Date",
        "updatedAt": "Date | null"
      }
    ],
    "isArchived": "boolean"
  }
}

  • Parameters:

    Name Type Required Description
    taskInstanceId String Yes Links this task to its TaskInstance container.
    title String Yes The title of the task.
    description String No A detailed description of the task.
    status Enum No The current status of the task. Valid values: todo, in_progress, in_review, done, blocked. Defaults to todo.
    priority Enum No The priority level of the task. Valid values: low, medium, high, urgent. Defaults to medium.
    assignees Array<String> No An array of MessagingContact IDs assigned to this task. Defaults to [].
    parentId String No The _id of the parent task, if this is a subtask.
    dueDate Date No The target completion date for the task.
    completedAt Date No The actual completion date of the task.
    tags Array<String> No An array of tags associated with the task. Defaults to [].
    comments Array<Object> No An array of comment objects associated with the task. Defaults to [].
    isArchived Boolean No Whether this specific task is archived. Defaults to false.

  • Response:

    {
  "success": true,
  "data": {
    "_id": "string",
    "taskInstanceId": "string",
    "title": "string",
    "description": "string | null",
    "status": "todo | in_progress | in_review | done | blocked",
    "priority": "low | medium | high | urgent",
    "assignees": ["string"],
    "parentId": "string | null",
    "dueDate": "Date | null",
    "completedAt": "Date | null",
    "createdAt": "Date",
    "updatedAt": "Date",
    "tags": ["string"],
    "comments": [
      {
        "commentId": "string (UUID)",
        "authorContactId": "string",
        "content": "string",
        "createdAt": "Date",
        "updatedAt": "Date | null"
      }
    ],
    "isArchived": "boolean"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.create",
    "params": {
      "taskInstanceId": "654321098765432109876543",
      "title": "New Feature Implementation",
      "description": "Develop the 'X' feature according to specifications.",
      "status": "todo",
      "priority": "high",
      "assignees": ["contact_id_1"]
    }
  }'

POST /api/rpc (Method: TaskRpc.update)

  • Description: Updates a task's details.

  • Request Body:

    {
  "method": "TaskRpc.update",
  "params": {
    "_id": "string",
    "title": "string",
    "description": "string | null",
    "status": "todo | in_progress | in_review | done | blocked",
    "priority": "low | medium | high | urgent",
    "assignees": ["string"],
    "dueDate": "Date | null",
    "completedAt": "Date | null",
    "tags": ["string"],
    "isArchived": "boolean"
  }
}

  • Parameters:

    Name Type Required Description
    _id String Yes The unique identifier of the task to update.
    title String No The updated title of the task.
    description String No The updated description of the task.
    status Enum No The updated status of the task. Valid values: todo, in_progress, in_review, done, blocked.
    priority Enum No The updated priority level of the task. Valid values: low, medium, high, urgent.
    assignees Array<String> No The updated array of MessagingContact IDs assigned to this task.
    dueDate Date No The updated target completion date for the task.
    completedAt Date No The updated actual completion date of the task.
    tags Array<String> No The updated array of tags associated with the task.
    isArchived Boolean No Whether this specific task is archived.

  • Response:

    {
  "success": true,
  "data": {
    "_id": "string",
    "taskInstanceId": "string",
    "title": "string",
    "description": "string | null",
    "status": "todo | in_progress | in_review | done | blocked",
    "priority": "low | medium | high | urgent",
    "assignees": ["string"],
    "parentId": "string | null",
    "dueDate": "Date | null",
    "completedAt": "Date | null",
    "createdAt": "Date",
    "updatedAt": "Date",
    "tags": ["string"],
    "comments": [
      {
        "commentId": "string (UUID)",
        "authorContactId": "string",
        "content": "string",
        "createdAt": "Date",
        "updatedAt": "Date | null"
      }
    ],
    "isArchived": "boolean"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.update",
    "params": {
      "_id": "654321098765432109876544",
      "status": "in_progress",
      "assignees": ["contact_id_1", "contact_id_2"]
    }
  }'

POST /api/rpc (Method: TaskRpc.delete)

  • Description: Deletes a task and all of its subtasks.

  • Request Body:

    {
  "method": "TaskRpc.delete",
  "params": {
    "_id": "string"
  }
}

  • Parameters:

    Name Type Required Description
    _id String Yes The unique identifier of the task to delete.

  • Response:

    {
  "success": true,
  "data": {
    "success": "boolean"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.delete",
    "params": {
      "_id": "654321098765432109876545"
    }
  }'

POST /api/rpc (Method: TaskRpc.findById)

  • Description: Retrieves a single task by its ID.

  • Request Body:

    {
  "method": "TaskRpc.findById",
  "params": {
    "_id": "string"
  }
}

  • Parameters:

    Name Type Required Description
    _id String Yes The unique identifier of the task to retrieve.

  • Response:

    {
  "success": true,
  "data": {
    "_id": "string",
    "taskInstanceId": "string",
    "title": "string",
    "description": "string | null",
    "status": "todo | in_progress | in_review | done | blocked",
    "priority": "low | medium | high | urgent",
    "assignees": ["string"],
    "parentId": "string | null",
    "dueDate": "Date | null",
    "completedAt": "Date | null",
    "createdAt": "Date",
    "updatedAt": "Date",
    "tags": ["string"],
    "comments": [
      {
        "commentId": "string (UUID)",
        "authorContactId": "string",
        "content": "string",
        "createdAt": "Date",
        "updatedAt": "Date | null"
      }
    ],
    "isArchived": "boolean"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.findById",
    "params": {
      "_id": "654321098765432109876546"
    }
  }'

POST /api/rpc (Method: TaskRpc.addComment)

  • Description: Adds a comment to a task.

  • Request Body:

    {
  "method": "TaskRpc.addComment",
  "params": {
    "taskId": "string",
    "content": "string"
  }
}

  • Parameters:

    Name Type Required Description
    taskId String Yes The ID of the task to add the comment to.
    content String Yes The content of the comment. Must not be empty.

  • Response:

    {
  "success": true,
  "data": {
    "commentId": "string (UUID)",
    "authorContactId": "string",
    "content": "string",
    "createdAt": "Date"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.addComment",
    "params": {
      "taskId": "654321098765432109876547",
      "content": "This task needs more details on the design."
    }
  }'

POST /api/rpc (Method: TaskRpc.createTaskTree)

  • Description: Creates a hierarchy of tasks (a tree) in a single operation.

  • Request Body:

    {
  "method": "TaskRpc.createTaskTree",
  "params": {
    "taskInstanceId": "string",
    "tasks": [
      {
        "title": "string",
        "description": "string | null",
        "status": "todo | in_progress | in_review | done | blocked",
        "priority": "low | medium | high | urgent",
        "assignees": ["string"],
        "dueDate": "Date | null",
        "completedAt": "Date | null",
        "tags": ["string"],
        "comments": [
          {
            "commentId": "string (UUID)",
            "authorContactId": "string",
            "content": "string",
            "createdAt": "Date",
            "updatedAt": "Date | null"
          }
        ],
        "isArchived": "boolean",
        "subtasks": [
          {
            "title": "string",
            "description": "string | null",
            "status": "todo | in_progress | in_review | done | blocked",
            "priority": "low | medium | high | urgent",
            "assignees": ["string"],
            "dueDate": "Date | null",
            "completedAt": "Date | null",
            "tags": ["string"],
            "comments": [
              {
                "commentId": "string (UUID)",
                "authorContactId": "string",
                "content": "string",
                "createdAt": "Date",
                "updatedAt": "Date | null"
              }
            ],
            "isArchived": "boolean",
            "subtasks": []
          }
        ]
      }
    ]
  }
}

  • Parameters:

    Name Type Required Description
    taskInstanceId String Yes The ID of the Task Instance (board) to add the tasks to.
    tasks Array<Object> Yes An array of task objects. Each object can contain a subtasks array for recursion. Minimum 1 task.
    tasks[].title String Yes The title of the task.
    tasks[].description String No A detailed description of the task.
    tasks[].status Enum No The current status of the task. Valid values: todo, in_progress, in_review, done, blocked. Defaults to todo.
    tasks[].priority Enum No The priority level of the task. Valid values: low, medium, high, urgent. Defaults to medium.
    tasks[].assignees Array<String> No An array of MessagingContact IDs assigned to this task. Defaults to [].
    tasks[].dueDate Date No The target completion date for the task.
    tasks[].completedAt Date No The actual completion date of the task.
    tasks[].tags Array<String> No An array of tags associated with the task. Defaults to [].
    tasks[].comments Array<Object> No An array of comment objects associated with the task. Defaults to [].
    tasks[].isArchived Boolean No Whether this specific task is archived. Defaults to false.
    tasks[].subtasks Array<Object> No An array of sub-task objects, recursively following the same structure.

  • Response:

    {
  "success": true,
  "data": [
    {
      "_id": "string",
      "taskInstanceId": "string",
      "title": "string",
      "description": "string | null",
      "status": "todo | in_progress | in_review | done | blocked",
      "priority": "low | medium | high | urgent",
      "assignees": ["string"],
      "parentId": "string | null",
      "dueDate": "Date | null",
      "completedAt": "Date | null",
      "createdAt": "Date",
      "updatedAt": "Date",
      "tags": ["string"],
      "comments": [
        {
          "commentId": "string (UUID)",
          "authorContactId": "string",
          "content": "string",
          "createdAt": "Date",
          "updatedAt": "Date | null"
        }
      ],
      "isArchived": "boolean"
    }
  ]
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.createTaskTree",
    "params": {
      "taskInstanceId": "654321098765432109876548",
      "tasks": [
        {
          "title": "Parent Task 1",
          "subtasks": [
            {
              "title": "Subtask 1.1"
            },
            {
              "title": "Subtask 1.2",
              "subtasks": [
                {
                  "title": "Sub-subtask 1.2.1"
                }
              ]
            }
          ]
        },
        {
          "title": "Parent Task 2"
        }
      ]
    }
  }'

POST /api/rpc (Method: TaskRpc.archiveTask)

  • Description: Archives or un-archives a specific task.

  • Request Body:

    {
  "method": "TaskRpc.archiveTask",
  "params": {
    "taskId": "string",
    "isArchived": "boolean"
  }
}

  • Parameters:

    Name Type Required Description
    taskId String Yes The ID of the task to archive or un-archive.
    isArchived Boolean Yes Set to true to archive the task, false to un-archive it.

  • Response:

    {
  "success": true,
  "data": {
    "_id": "string",
    "taskInstanceId": "string",
    "title": "string",
    "description": "string | null",
    "status": "todo | in_progress | in_review | done | blocked",
    "priority": "low | medium | high | urgent",
    "assignees": ["string"],
    "parentId": "string | null",
    "dueDate": "Date | null",
    "completedAt": "Date | null",
    "createdAt": "Date",
    "updatedAt": "Date",
    "tags": ["string"],
    "comments": [
      {
        "commentId": "string (UUID)",
        "authorContactId": "string",
        "content": "string",
        "createdAt": "Date",
        "updatedAt": "Date | null"
      }
    ],
    "isArchived": "boolean"
  }
}

  • Example (cURL):

    curl -X POST https://api.example.com/api/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "method": "TaskRpc.archiveTask",
    "params": {
      "taskId": "654321098765432109876549",
      "isArchived": true
    }
  }'