Skip to main content

Tasks

Complete reference for working with tasks in the Vaiz SDK.

Creating Tasks​

Basic Task​

from vaiz import VaizClient
from vaiz.models import CreateTaskRequest, TaskPriority

client = VaizClient(api_key="...", space_id="...")

task = CreateTaskRequest(
    name="Implement user authentication",
    board="board_id",
    group="group_id",  # Optional - specify if board has groups
    priority=TaskPriority.High
)

response = client.create_task(task)
print(f"Created: {response.task.id}")
Optional Fields
  • group - Optional if board doesn't use groups
  • project - Optional, API determines from board

Task with Description​

Use the description parameter for convenience:

task = CreateTaskRequest(
    name="Task Name",
    board="board_id",
    group="group_id"
)

response = client.create_task(
    task,
    description="Task description content"
)

Task with Dates​

from datetime import datetime

task = CreateTaskRequest(
    name="Project Milestone",
    board="board_id",
    group="group_id",
    due_start=datetime(2025, 2, 1, 9, 0),
    due_end=datetime(2025, 2, 15, 17, 0)
)

response = client.create_task(task)

Task with Files (Easy Way)​

Upload and attach file in one step:

from vaiz.models import TaskUploadFile
from vaiz.models.enums import UploadFileType

task = CreateTaskRequest(
    name="Review Document",
    board="board_id",
    group="group_id"
)

# File automatically uploaded and attached
response = client.create_task(
    task,
    file=TaskUploadFile(path="doc.pdf", type=UploadFileType.Pdf)
)

Task with Files (Manual Way)​

Or upload manually and create TaskFile:

from vaiz.models import TaskFile

# Upload file
file_response = client.upload_file("doc.pdf", UploadFileType.Pdf)

# Create TaskFile
task_file = TaskFile(
    url=file_response.file.url,
    name=file_response.file.name,
    ext=file_response.file.ext,
    id=file_response.file.id,
    type=file_response.file.type,
    dimension=file_response.file.dimension
)

# Create task
task = CreateTaskRequest(
    name="Review Document",
    board="board_id",
    group="group_id",
    files=[task_file]
)

response = client.create_task(task)

Task with Blockers​

Create tasks with dependency relationships:

# Task that is blocked by another task
task = CreateTaskRequest(
    name="Implement Feature",
    board="board_id",
    group="group_id",
    blockers=["design_task_id"]  # This task depends on design task
)

response = client.create_task(task)

Learn more in Task Blockers documentation.

Updating Tasks​

from vaiz.models import EditTaskRequest

edit = EditTaskRequest(
    task_id="task_id",
    name="Updated Name",
    completed=True,
    priority=TaskPriority.High
)

response = client.edit_task(edit)

Getting Tasks​

Single Task​

response = client.get_task("PRJ-123")
task = response.task

Multiple Tasks​

from vaiz.models import GetTasksRequest

request = GetTasksRequest(
    completed=False,
    assignees=["user_id"],
    limit=50
)

response = client.get_tasks(request)
for task in response.payload.tasks:
    print(f"{task.hrid}: {task.name}")

Moving Tasks Between Groups​

To move tasks between board groups, use the move_tasks method. This is the correct way to change a task's group — edit_task does not support group changes.

Move a single task​

from vaiz.models import MoveTaskItem, MoveTasksRequest

move_request = MoveTasksRequest(
    moves=[
        MoveTaskItem(
            task_id="task_id",
            to_group_id="target_group_id",
            to_index=0  # Position in the target group
        )
    ]
)

response = client.move_tasks(move_request)
print(f"Moved: {response.payload.success_ids}")
print(f"Failed: {response.payload.failed_ids}")

Move multiple tasks at once​

move_request = MoveTasksRequest(
    moves=[
        MoveTaskItem(task_id="task_1", to_group_id="group_b", to_index=0),
        MoveTaskItem(task_id="task_2", to_group_id="group_b", to_index=1),
        MoveTaskItem(task_id="task_3", to_group_id="group_c", to_index=0),
    ]
)

response = client.move_tasks(move_request)
tip

You can move tasks to different groups in a single request. Each move specifies its own target group and position.

Task Descriptions​

Tasks store descriptions as structured JSON documents. The SDK provides convenient methods to work with descriptions directly from Task objects.

Important: Task descriptions support rich content using the same document structure format as standalone documents. You can use replace_json_document to create formatted task descriptions with headings, lists, links, and more.

Get Task Description​

# Get from task object
task_response = client.get_task("PRJ-123")
task = task_response.task
document_id = task.document

# Get document content
description = client.get_json_document(document_id)
print(description)  # JSON structure

Update Task Description​

Replace task description completely:

# Get task
task_response = client.get_task("PRJ-123")
document_id = task_response.task.document

# Update description
new_content = """
# Updated Description

This completely replaces the previous content.

## Features
- Complete replacement
- Plain text support
- Direct API access
"""

client.replace_document(
    document_id=document_id,
    description=new_content
)

Rich Formatted Descriptions​

For rich content with formatting, lists, and links, use replace_json_document:

from vaiz import heading, paragraph, text, bullet_list

# Get task
task_response = client.get_task("PRJ-123")
document_id = task_response.task.document

# Create rich content
content = [
    heading(1, "Task Overview"),
    paragraph(
        "This task requires ",
        text("immediate attention", bold=True),
        "."
    ),
    heading(2, "Requirements"),
    bullet_list(
        "Review design mockups",
        "Update documentation",
        "Test functionality"
    ),
    paragraph(
        "See ",
        text("project docs", link="https://docs.example.com"),
        " for details."
    )
]

# Replace with rich content
client.replace_json_document(document_id, content)

See Document Structure for complete format reference and Document Structure Helpers for helper functions.

Using Task Helper Methods​

The Task model provides convenient helper methods:

# Get task
task_response = client.create_task(task)
task_obj = task_response.task

# Get description using helper
description = task_obj.get_task_description(client)
print(description)

# Update description using helper
task_obj.update_task_description(
    client, 
    "New task description content"
)

Full Workflow Example​

from vaiz.models import CreateTaskRequest

# 1. Create task with initial description
task = CreateTaskRequest(
    name="Documentation Task",
    board="board_id",
    group="group_id"
)

response = client.create_task(
    task,
    description="Initial task description"
)

# 2. Get task object
task_obj = response.task

# 3. Update description later
task_obj.update_task_description(
    client,
    "Updated task description with more details"
)

# 4. Read current content
content = task_obj.get_task_description(client)
print(content)

Programmatic Description Updates​

from datetime import datetime

def add_status_update(task_id: str, status: str):
    """Append status update to task description"""
    
    # Get task
    task_response = client.get_task(task_id)
    doc_id = task_response.task.document
    
    # Get current content
    current = client.get_json_document(doc_id)
    
    # Add status update
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
    new_content = f"""
{current}

---
**Status Update ({timestamp})**: {status}
"""
    
    client.replace_document(doc_id, new_content)

# Usage
add_status_update("PRJ-123", "Design phase completed")
Advanced Usage

If you need more control, you can work directly with the document ID from task.document field using the Documents API methods.

See Also​