query_tasks

Category: tasks
Access: read
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Lists live tasks and notes with combined filters, full-text search, sorting, and paging. The default workhorse view: finished work stays out unless explicitly asked for, and every non-empty page ships with a markdown rendering.

Arguments

Optional: include_completed, limit, offset, overdue_only, parent_id, priority, project, search, section, sort_by, sort_order, status, summary_only, type.

include_completed.
limit.
offset.
overdue_only. Note: Shows only past-due content and always excludes finished content, even with include_completed.
parent_id.
priority.
project.
search. Note: Re-ranks matches by relevance and adds a per-item rank; sort order has little visible effect on that path.
section.
sort_by. Note: Allowlist: created_at, updated_at, due_date, priority, status, title, project, section, type. Anything else is rejected; each field has its own sensible default direction.
sort_order.
status. Note: Passing an explicit status (or include_completed) opts back in to done, archived, and cancelled content; otherwise it is excluded.
summary_only.
type.

Result

JSON object with tasks (full entries, or summaries with summary_only), count, total, offset, limit, and markdown. Paging adds has_more and next_offset when content remains. Empty results return tasks [], count 0, total, and the message No tasks match.

Boundaries

Only content inside the caller's project grants is ever searched or counted; anything else reads as no match. Out-of-scope project filters yield the empty shape, never a denial.

Lifecycle / side effects

Pure read; nothing is created, moved, or annotated as a side effect.

Errors

Unknown arguments and bad types are rejected (strict validator). Unknown sort_by or sort_order values are rejected with an invalid_sort message naming the allowlist.

Example

{
  "limit": 5,
  "section": "today"
}

Result shape:

{
  "count": 1,
  "limit": 5,
  "markdown": "| # | Title | Status | Priority | Section | Due | Project | Created | Notes |",
  "offset": 0,
  "tasks": [
    {
      "id": "<uuid>",
      "priority": "high",
      "section": "today",
      "status": "not_started",
      "title": "Draft Paul pack README"
    }
  ],
  "total": 1
}