Skip to main content
POST
/
api
/
boards
/
{board_id}
/
tasks
Create Task
curl --request POST \
  --url https://api.example.com/api/boards/{board_id}/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>",
  "status": "<string>",
  "priority": "<string>",
  "due_at": "<string>",
  "assigned_agent_id": "<string>",
  "created_by_user_id": "<string>",
  "depends_on_task_ids": [
    {}
  ],
  "tag_ids": [
    {}
  ],
  "custom_field_values": {}
}
'
{
  "id": "<string>",
  "board_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "status": "<string>",
  "priority": "<string>",
  "due_at": "<string>",
  "assigned_agent_id": "<string>",
  "created_by_user_id": "<string>",
  "in_progress_at": "<string>",
  "depends_on_task_ids": [
    {}
  ],
  "blocked_by_task_ids": [
    {}
  ],
  "is_blocked": true,
  "tag_ids": [
    {}
  ],
  "tags": [
    {}
  ],
  "custom_field_values": {},
  "created_at": "<string>",
  "updated_at": "<string>"
}
Create a new task on a board with optional dependencies, tags, and custom field values. The task will be validated against dependency rules and custom field requirements.

​
Path Parameters

​
board_id
string
required
The UUID of the board to create the task in

​
Request Body

​
title
string
required
Task title
​
description
string
Detailed task description
​
status
string
default:"inbox"
Initial task statusAllowed values: inbox, in_progress, review, done
​
priority
string
default:"medium"
Task priority level (e.g., low, medium, high, critical)
​
due_at
string
ISO 8601 timestamp for task due date
​
assigned_agent_id
string
UUID of the agent to assign this task to
​
created_by_user_id
string
UUID of the user creating the task (auto-populated from auth context if not provided)
​
depends_on_task_ids
array
Array of task UUIDs this task depends on. Dependencies must:
  • Exist on the same board
  • Not create circular dependency chains
  • Not include the task itself
​
tag_ids
array
Array of tag UUIDs to apply to this task
​
custom_field_values
object
Key-value pairs for custom field values. Keys must match board-configured custom field definitions.

​
Response

​
id
string
Newly created task UUID
​
board_id
string
Board UUID
​
title
string
Task title
​
description
string
Task description
​
status
string
Task status
​
priority
string
Task priority
​
due_at
string
Due date timestamp
​
assigned_agent_id
string
Assigned agent UUID
​
created_by_user_id
string
Creator user UUID
​
in_progress_at
string
Timestamp when task entered in_progress (null for new tasks)
​
depends_on_task_ids
array
Dependency task UUIDs
​
blocked_by_task_ids
array
Task UUIDs blocking this task
​
is_blocked
boolean
Whether task is blocked by dependencies
​
tag_ids
array
Applied tag UUIDs
​
tags
array
Tag objects with id, name, and color
​
custom_field_values
object
Custom field key-value pairs
​
created_at
string
Creation timestamp
​
updated_at
string
Last update timestamp

​
Example Request

curl -X POST "https://api.openclaw.ai/api/boards/123e4567-e89b-12d3-a456-426614174000/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user authentication",
    "description": "Add OAuth2 authentication flow with JWT tokens",
    "status": "inbox",
    "priority": "high",
    "due_at": "2026-03-15T18:00:00Z",
    "depends_on_task_ids": [
      "660e8400-e29b-41d4-a716-446655440001"
    ],
    "tag_ids": [
      "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f"
    ],
    "custom_field_values": {
      "effort_points": 5,
      "sprint": "Sprint 12"
    }
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "board_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Implement user authentication",
  "description": "Add OAuth2 authentication flow with JWT tokens",
  "status": "inbox",
  "priority": "high",
  "due_at": "2026-03-15T18:00:00Z",
  "assigned_agent_id": null,
  "created_by_user_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "in_progress_at": null,
  "depends_on_task_ids": [
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "blocked_by_task_ids": [
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "is_blocked": true,
  "tag_ids": [
    "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f"
  ],
  "tags": [
    {
      "id": "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f",
      "name": "backend",
      "color": "#3b82f6"
    }
  ],
  "custom_field_values": {
    "effort_points": 5,
    "sprint": "Sprint 12"
  },
  "created_at": "2026-03-05T14:22:00Z",
  "updated_at": "2026-03-05T14:22:00Z"
}

​
Error Responses

​
409 Conflict - Blocked by Dependencies

Returned when creating a task with incomplete dependencies while also assigning it or setting status to non-inbox: 
{
  "detail": {
    "message": "Task is blocked by incomplete dependencies.",
    "code": "task_blocked_cannot_transition",
    "blocked_by_task_ids": [
      "660e8400-e29b-41d4-a716-446655440001"
    ]
  }
}

​
409 Conflict - Dependency Cycle

{
  "detail": "Dependency cycle detected. Remove the cycle before saving."
}

​
404 Not Found - Missing Dependencies

{
  "detail": {
    "message": "One or more dependency tasks were not found on this board.",
    "missing_task_ids": [
      "660e8400-e29b-41d4-a716-446655440001"
    ]
  }
}

​
422 Unprocessable Entity - Invalid Custom Fields

{
  "detail": {
    "message": "Unknown custom field keys for this board.",
    "unknown_field_keys": ["invalid_field"]
  }
}

​
Notes

  • Blocked tasks (with incomplete dependencies) cannot be assigned or moved out of inbox status
  • Dependencies must exist on the same board and cannot create cycles
  • Custom field values are validated against board-specific field definitions
  • Required custom fields must have values (or use their default values)
  • The board lead agent is automatically notified when a new task is created
  • If an agent is assigned, they receive a notification via the gateway

Build docs developers (and LLMs) love

Get started for freeTalk to us