pm_create_task
Create a task. In the result, title/webUrl are for presentation; displayKey is the optional visible key. Keep key/identifier for API calls and do not expose a hidden raw key in the summary. References are name-based: status/priority/level/taskType are names; assignees are emails; tags are strings (auto-created if missing); customFields is a {name: value} map. list is the task-list identifier (tl_…). For subtasks, set parent to a task key or identifier (omit list and the parent's list is used). Task type is OPTIONAL: omit taskType to inherit the closest non-null default along the three-level chain list → folder → space. There's NO workspace-level fallback — if all three are null the task is created untyped (taskType: null in the response), which is a valid persistent state. Use pm_list_task_types to see what types this workspace has (9 SYSTEM rows seeded at workspace creation, plus any CUSTOM ones). MANDATORY CUSTOM FIELDS: a list can mark custom fields required (isMandatory, per field via pm_get_workspace_context). Populate them in customFields on create AND update — the API rejects a write that leaves one empty with HTTP 400 errorCode VALIDATION_ERROR, details.field = the field's display name; the message also names it (e.g. Mandatory custom field 'Priority' requires a value). Fix and retry; don't ask the user as a substitute. API-key scope: tasks:write.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Task-list identifier (tl_…); omit if parent is set | |
| tags | No | ||
| level | No | ||
| title | Yes | ||
| nextTo | No | Task key/identifier to position next to | |
| parent | No | Parent task key or identifier (for subtasks) | |
| status | No | Status name (e.g. "In Progress") | |
| account | No | Multi-account auth only: name of the account from X-Dutify-Accounts to use for this call. Ignored in single-account mode (X-API-Key header). When multiple accounts are configured and this is omitted, the call fails with ACCOUNT_REQUIRED listing the available names. list_accounts never requires a selection. | |
| dueDate | No | ISO-8601 datetime | |
| priority | No | ||
| taskType | No | ||
| assignees | No | Emails | |
| isPrivate | No | ||
| startDate | No | ISO-8601 datetime | |
| workspace | No | Workspace identifier or exact name for this call. Overrides the configured workspace. For personal keys, discover candidates with list_workspaces and select explicitly. Does not change other calls or expand a workspace key's access. | |
| description | No | ||
| customFields | No | {fieldName: value}. Include every field the list marks mandatory (isMandatory, see pm_get_workspace_context) — a missing required field is rejected with a 400 VALIDATION_ERROR (details.field = field display name, also named in the message). Note on email: multi-value is supported but OPT-IN per field via visualSettings.allowsMultiple (default false, and settable only on the rich custom-field endpoints, not the lite ones). When enabled, pass an array of email strings and/or {email,displayName,verified} objects, max 200 elements (over that = 400 "Array value exceeds maximum size of 200 elements"). When not enabled, pass a string or object — an array is rejected with "Email field value must be a string or object", and the fix is to enable allowsMultiple, not to use a comma-separated string (that fails format validation). phone/website/location remain single-value. | |
| estimatedTime | No | Minutes | |
| idempotencyKey | No | Optional. Pass a UUID to dedupe retries within a 5-minute window. The same key inside the window returns 409 DUPLICATE_REQUEST regardless of body — query by name/identifier to find what was created on the first attempt; never assume the second call failed. | |
| recurrenceRule | No | iCal RRULE string |