What is TaskNotes API?

An HTTP API exposed by the TaskNotes plugin to manage Obsidian tasks remotely.

Do I need authentication?

If you set a token in TASKNOTES_API_KEY, include it via the environment; otherwise no auth is required.

How do I view available values (statuses, priorities, projects)?

Run uv run scripts/tasks.py options --table to list current options from TaskNotes.

Obsidian Tasknotes

Scanned

@benoitjadinon

npx machina-cli add skill @benoitjadinon/obsidian-plugin-tasknotes --openclaw

Files (1)

SKILL.md

3.5 KB

TaskNotes Skill

Manage Obsidian tasks via the TaskNotes plugin HTTP API.

Requirements

TaskNotes plugin installed in Obsidian
Enable HTTP API in TaskNotes settings:
- Open Obsidian Settings → TaskNotes
- Enable "HTTP API" toggle
- Set API port (default: 8080)
- API token: leave empty for no auth, or set a token for security
Environment variables in .env file at vault root (if using auth):
```
TASKNOTES_API_PORT=8080
TASKNOTES_API_KEY=your_token_here
```
If TaskNotes has no auth token set, you don't need a .env file.

CLI Commands

# List all tasks
uv run scripts/tasks.py list

# List by status (use your configured status values)
uv run scripts/tasks.py list --status "in-progress"

# List by project
uv run scripts/tasks.py list --project "My Project"

# Create task
uv run scripts/tasks.py create "Task title" --project "My Project" --priority high

# Create task with scheduled time
uv run scripts/tasks.py create "Meeting prep" --scheduled "2025-01-15T14:00:00"

# Update task status
uv run scripts/tasks.py update "Tasks/task-file.md" --status done

# Add/update task description
uv run scripts/tasks.py update "Tasks/task-file.md" --details "Additional context here."

# Delete task
uv run scripts/tasks.py delete "Tasks/task-file.md"

# Get available options (statuses, priorities, projects)
uv run scripts/tasks.py options --table

# Human-readable output (add --table)
uv run scripts/tasks.py list --table

Task Properties

Status and Priority values: Configured in your TaskNotes plugin settings. Run options command to see available values:

uv run scripts/tasks.py options --table

Other fields:

projects - Array of project links, e.g. ["[[Project Name]]"]
contexts - Array like ["office", "energy-high"]
due - Due date (YYYY-MM-DD)
scheduled - Scheduled date/time (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
timeEstimate - Minutes (number)
tags - Array of tags
details - Task description (writes to markdown body, not frontmatter)

API Reference

Base URL: http://localhost:8080/api

Method	Endpoint	Description
GET	/tasks	List tasks (supports filters)
POST	/tasks	Create task
GET	/tasks/{id}	Get single task
PUT	/tasks/{id}	Update task
DELETE	/tasks/{id}	Delete task
GET	/filter-options	Available statuses, priorities, projects

Query Parameters for GET /tasks

status - Filter by status
project - Filter by project name
priority - Filter by priority
tag - Filter by tag
overdue - true/false
sort - Sort field
limit - Max results
offset - Pagination offset

When to Use

"create a task for X" → create task
"show my tasks" → list all tasks
"show in-progress tasks" → list --status in-progress
"mark X as done" → update task status to done
"what should I work on" → list tasks by status

Example Workflow

# Morning: Check what to work on
uv run scripts/tasks.py list --status in-progress --table
uv run scripts/tasks.py list --limit 5 --table

# Create task linked to project
uv run scripts/tasks.py create "Finish landing page" \
  --project "Website Redesign" \
  --priority high

# Complete a task
uv run scripts/tasks.py update "Tasks/finish-landing-page.md" --status done

Source

git clone https://clawhub.ai/benoitjadinon/obsidian-plugin-tasknotesView on GitHub

Overview

This skill enables you to manage Obsidian tasks through the TaskNotes HTTP API. Create, list, query by status or project, update status, delete tasks, or check what you need to do. It relies on the TaskNotes plugin and its HTTP API, with optional authentication.

How This Skill Works

The skill communicates with the TaskNotes API at http://localhost:8080/api, translating natural actions into API calls such as GET /tasks, POST /tasks, PUT /tasks/{id}, and DELETE /tasks/{id}. Optional environment variables (TASKNOTES_API_PORT and TASKNOTES_API_KEY) control the port and authentication when enabled.

When to Use It

create a task for X
show my tasks
show in-progress tasks
mark X as done
what should I work on

Quick Start

Step 1: Install TaskNotes and enable the HTTP API in Obsidian; configure the API port and optional token in .env if using auth.
Step 2: Use TaskNotes CLI commands, e.g., uv run scripts/tasks.py list or uv run scripts/tasks.py create "New task" --project "Project A" --priority medium.
Step 3: Verify available options and results with uv run scripts/tasks.py options --table and by inspecting the API response.

Best Practices

Ensure TaskNotes is installed and HTTP API is enabled in Obsidian.
Use the options command to fetch current statuses, priorities, and projects.
Use consistent project names and proper date formats (YYYY-MM-DD or ISO) for scheduling.
Include details or time estimates when creating tasks to provide context.
Use the returned task IDs for updates or deletes and prefer --table for readability.

Example Use Cases

uv run scripts/tasks.py list
uv run scripts/tasks.py list --status "in-progress"
uv run scripts/tasks.py list --project "My Project"
uv run scripts/tasks.py create "Task title" --project "My Project" --priority high
uv run scripts/tasks.py update "Tasks/task-file.md" --status done

Frequently Asked Questions

Add this skill to your agents