Create Task
vault_create_taskCreate a correctly formatted task in an Obsidian note or Kanban board in one call, with heading, dates, priority, block ID, and optional checklist items.
Instructions
Create a correctly-formatted task in one call — description, target heading, dates, priority, block_id, and optional checklist sub-items. The task is always created as todo, with its created date (➕) set to today; set in_progress later with vault_update_task. Override format only at the user's request. A retried call with no block_id (a Kanban sub-task) creates it again, so after a timeout or lost response, re-read the note before retrying.
Example: vault_create_task({ path: "TASKS.md", description: "Fix login bug", block_id: "fix-login", heading: "Active", priority: "high", due: "2026-09-15" }) — a card in a Kanban board's Active lane Example: vault_create_task({ path: "TASKS.md", description: "Sub-bug", parent_block_id: "fix-login", due: "2026-09-01" }) — full sub-task under fix-login Example: vault_create_task({ path: "Projects/plan.md", description: "Quick fix", block_id: "quick-fix", parent_line: 42 }) — sub-task in a regular note under a parent identified by line number Example: vault_create_task({ path: "TASKS.md", description: "Write release notes", block_id: "release-notes", heading: "Active", position: 3 }) — insert as the 3rd card in the lane
When to use: Creating a new task card on a board or in a note. For lightweight checklist items under an existing card (no metadata), use vault_update_task's add_subtasks param instead.
Parameters:
heading is required on Kanban boards (notes with a kanban-plugin property) unless a parent is given.
parent_block_id / parent_line: pass at most one. Either is mutually exclusive with heading — a sub-task lives wherever its parent lives.
block_id / subtasks: block_id is required, except on a Kanban sub-task, where it is refused, as is a subtasks item ending in a ^block-id on a board.
position: ignored without a heading, and under a parent, where the sub-task goes after the parent's last sub-item.
recurrence: a rule ending "when done" bases the next occurrence on the completion day; a task with no dates recurs as a dateless copy.
Errors: (messages use camelCase names, e.g. blockId for block_id)
"note not found" — path does not exist; check the path with vault_list_notes
"path must end in …" — add the .md extension
"absolute path blocked" / "path traversal blocked" / "hidden path blocked" — pass a vault-relative path with no dot-prefixed part
"heading required for Kanban boards" — pass heading with the target lane
"heading "X" not found; available: ..." — the message lists the note's headings
"cannot place at position P under "X" — the heading appears N times" — integer position on a note with duplicate heading names; use "top" or "bottom" (they place under the first match), or rename one section to make it unique
"parent task not found" — parent_block_id or parent_line doesn't resolve to a task outside a fenced code block or %% %% comment; re-read the parent's block_id or line with vault_list_tasks
"parent task ambiguous" — more than one task line ends in that ^id (the message lists their line numbers); pass parent_line instead
"checkbox "[c]" is a NON_TASK status" / "no checkbox symbol for status ..." — in the Tasks plugin's status settings, the parent's checkbox character (c) is typed NON_TASK, or todo has no symbol and the default [ ] character has another type; the user changes that character's type or adds a todo symbol there, then restarts the server
"parentBlockId and parentLine are mutually exclusive" / "parent and heading are mutually exclusive" — drop one
"blockId ... already exists in this note" / "blockId ... contains invalid characters" — pick a block_id no other line in the note ends in; the invalid-characters message names the allowed characters
"blockId is required" — pass block_id
"blockId is not allowed on a sub-task on a Kanban board" / "subtask ... ends in a block ID" — the message names what to drop
"description is empty" / "subtasks cannot contain an empty item" / "description must be a single line" / "subtasks items must be a single line" — pass visible text on a single line
"taskId ... contains invalid characters" / "dependsOn entry ... contains invalid characters" — the message names the allowed characters
"unrecognized recurrence rule ..." — the message gives example rules
"invalid date: …" — the message names the expected format
"concurrent write in progress" — another write to this note is in flight; retry
"ENAMETOOLONG: …" or another filesystem error — the message says what to do
"properties block …" — the note's properties block can't be read, or a rewrite would lose it; the error says how to repair it
"the note would open with a properties block …" — a note without properties would start with --- lines around text that can't be properties; the error says how to avoid it
Obsidian syntax: When description or subtasks text ends in a field the plugin's parser recognizes (an emoji field like "🔁 every week", or a Dataview [key:: value] field), with only other recognized fields after it, that text is read back as metadata. The write still succeeds; reword the text to clear the advisories the result carries.
Returns: JSON { path, line, description, block_id, heading, subtasks, changes, advisories } — line is the new task's 1-based line number in the file; block_id is omitted when the task has none (line is then its handle); heading is the nearest heading above the new task (omitted when the note has none); subtasks lists each checklist item written as { line, description } (omitted when none); changes lists every field written as "field: (none) → value", and checklist items as "subtasks: 0 → N"; advisories (omitted when the line round-trips clean) lists one sentence per place the stored line parses back differently than submitted — see Obsidian syntax above.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>",
"description": "<description>"
},
"name": "vault_create_task"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due | No | Deadline (📅), YYYY-MM-DD, calendar-validated. Omit when there is no deadline. | |
| path | Yes | Vault-relative path to the note (must end in ".md"). The note must already exist. Use the exact letter case. | |
| start | No | Earliest day work can begin (🛫), YYYY-MM-DD, calendar-validated. | |
| format | No | Field format. Default: auto-detected from .obsidian/ config, falling back to emoji. | |
| heading | No | Target heading's text, without the # marks, matched exactly. On a regular note, omit to append at end of body. | |
| task_id | No | Tasks plugin 🆔 identifier other tasks can name in depends_on — letters, digits, hyphens, and underscores; separate from block_id. | |
| block_id | No | The ^block-id (without the ^) for stable identification — letters, digits, and hyphens only ([a-zA-Z0-9-]+), unique within the note. | |
| position | No | Where within the heading section the task is placed: "top" first in the section, "bottom" at the end of the section, or a 1-based integer for an exact slot among the section's top-level tasks (a Kanban lane's cards; nested tasks are not counted). A position past the count lands directly below the last top-level task (unlike "bottom", which appends after any non-task text at the end of the section). Defaults to "bottom" ("top" on Kanban boards set to new-card-insertion-method: "prepend"). | |
| priority | No | Priority signifier: highest 🔺, high ⏫, medium 🔼, low 🔽, lowest ⏬. Omit for normal priority — no signifier is written. | |
| subtasks | No | Checklist sub-items: text-only todo lines indented under the card, with no metadata (not even ➕). For a sub-task with dates or priority, make a separate call with parent_block_id. | |
| scheduled | No | Day the work is planned for (⏳), YYYY-MM-DD, calendar-validated. | |
| depends_on | No | Tasks plugin ⛔ dependency IDs (🆔 values of other tasks), not checked against existing tasks. Omit when there are no dependencies. | |
| recurrence | No | Tasks plugin 🔁 rule in natural language (e.g. "every week", "every month on the 15th", "every 2 weeks when done"). Completing the task spawns its next occurrence. | |
| description | Yes | The task text (before metadata fields). | |
| parent_line | No | 1-based line number of an existing task to nest under as a sub-task. Fragile if the file changed since the line was read. | |
| on_completion | No | Tasks plugin 🏁 onCompletion action. "delete" removes the task line and its children on completion; "keep" leaves it in place, as omitting the field does. | |
| parent_block_id | No | ^block-id (without the ^) of an existing task to nest under as a sub-task. |