Create task

What "done" means for this task — the checkable bar the result is judged against, not instructions. Write it as conditions someone can verify ("tests pass on the branch tip", "page loads under 200ms"). Read it before you start and check your work against it before proposing completion.

Long-form write-up for the task, as HTML — this is what the rich-text editor reads and writes, so send HTML, not markdown. Send the tags raw — do not HTML-escape them (<p>x</p>, never <p>x</p>), or the write-up renders as literal text. Supported: <h1>-<h3>, <p>, <strong>, <em>, <ul>/<ol>/<li>, <a>, <code>, <pre>, <blockquote>, <table>/<tr>/<th>/<td>, and checklists as <ul data-type="taskList"><li data-type="taskItem" data-checked="false">. Use notes instead for a short one-liner.

File this task under a goal (North Star) as an action step toward it. Get ids from list_goals.

YYYY-MM-DD. Optional: the day work is meant to begin. With due_date it is the task's span on the human's Gantt chart; nothing schedules or reminds off it.

YYYY-MM-DD

Optional local wall-clock time on due_date, 24-hour "HH:MM". A task with one is scheduled AT that time instead of being packed into a free slot.

true = hard deadline (must finish on/before due_date); false (default) = soft, a suggested date

true = parked, waiting on someone else. A parked task stays on the board under "Waiting" but leaves the human's calendar feed, Plan my day and Today until its resurface_date arrives (or indefinitely, with none) — so it stops being time-blocked into every day while the ball is in someone else's court.

YYYY-MM-DD. The day a parked (waiting) task comes back onto the human's calendar and into Today. Only meaningful alongside waiting=true.

Only on an account with an agent roster (list_agents): pins the task to a named agent. Must be your OWN lane — a task you create lands in your queue, never another agent's; use handoff_task to pass work on. Implies assignee=claude. Without it, an assignee=claude task you create is pinned to your lane anyway.

Task length in minutes

1–5 rating of how much this moves the needle (feeds the Value/priority ranking)

Optional payout/value of this task (dollars, points, etc.); boosts its priority ranking

URLs/paths the agent should read for context

Structured outputs you produced — {label, url, kind, content}. content is the document itself so a human can read and approve it without leaving Done; url is for something that genuinely lives elsewhere. kind says what the document is — markdown (the default), html, or pdf as base64. The output-side counterpart to references.

What this deliverable holds. Omit for markdown, which is the default and the right answer for a draft, summary, report or plan. Use "html" only for a page you actually generated as HTML — it is rendered in a locked-down sandbox that cannot run scripts or reach the network, so a page that depends on either will look wrong. Use "pdf" with base64 in content for a small PDF, or with artifact_id for a large one. Use "binary" for anything else you uploaded — a screenshot, a spreadsheet, a zip — which is always an artifact_id and has no inline form.

The document itself, so a human can read it without leaving Done. Markdown or HTML as text, capped at 10,000 characters each (40,000 across the task). A pdf goes here as base64, capped at 800,000 base64 characters (about 600 kB, and 1,200,000 across the task). Put anything larger behind a url rather than truncating it.

An artifact you uploaded, instead of inline content (the two are mutually exclusive). Upload first: call create_artifact_upload with {task_id, label, filename, kind, size_bytes}, then PUT the raw bytes to the one-time upload_url it returns — no Authorization header, the link itself is the credential, and it expires 15 minutes after you request it. Use the artifact_id it returned here. To revise the document later, call create_artifact_upload again with the SAME artifact_id — this pointer keeps working and starts resolving to the new file as soon as its bytes land. Done keeps only that latest file: the previous one is queued for deletion once the replacement is safely stored, so don't rely on being able to fetch an earlier upload back.

What the downloaded file should be called. Ignored for the text kinds, and sanitised before use — the extension comes from an allow-list, not from you.

Optional. One key per operation: pass the same key only when retrying this exact call, so a retry after a timeout replays the first result (a key already used on a different tool is refused, and keys expire after 48 hours) instead of creating a duplicate task.