TaskNotes

TaskNotes HTTP API

The TaskNotes HTTP API provides local HTTP access to tasks, time tracking, pomodoro, calendars, webhooks, and NLP parsing.

Availability

  • Desktop only
  • Disabled by default
  • Started when Obsidian starts and TaskNotes API is enabled
  • Not available on mobile

Enable it in Settings -> TaskNotes -> Integrations -> HTTP API.

Base URL

http://localhost:{PORT}

Default port is 8080.

Authentication

Authentication is optional.

  • If apiAuthToken is empty, all API requests are accepted.
  • If apiAuthToken is set, send Authorization: Bearer <token>.

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/health

Response Format

Success:

{
  "success": true,
  "data": {}
}

Error:

{
  "success": false,
  "error": "Error message"
}

Endpoint Index

System

  • GET /api/health
  • GET /api/docs
  • GET /api/docs/ui
  • POST /api/nlp/parse
  • POST /api/nlp/create

Tasks

  • GET /api/tasks
  • POST /api/tasks
  • GET /api/tasks/:id
  • PUT /api/tasks/:id
  • DELETE /api/tasks/:id
  • POST /api/tasks/:id/toggle-status
  • POST /api/tasks/:id/archive
  • POST /api/tasks/:id/complete-instance
  • POST /api/tasks/query
  • GET /api/filter-options
  • GET /api/stats

Time Tracking

  • POST /api/tasks/:id/time/start
  • POST /api/tasks/:id/time/start-with-description
  • POST /api/tasks/:id/time/stop
  • GET /api/tasks/:id/time
  • GET /api/time/active
  • GET /api/time/summary

Pomodoro

  • POST /api/pomodoro/start
  • POST /api/pomodoro/stop
  • POST /api/pomodoro/pause
  • POST /api/pomodoro/resume
  • GET /api/pomodoro/status
  • GET /api/pomodoro/sessions
  • GET /api/pomodoro/stats

Calendars

  • GET /api/calendars
  • GET /api/calendars/google
  • GET /api/calendars/microsoft
  • GET /api/calendars/subscriptions
  • GET /api/calendars/events

Webhooks

  • POST /api/webhooks
  • GET /api/webhooks
  • DELETE /api/webhooks/:id
  • GET /api/webhooks/deliveries

See docs/webhooks.md for event and transform details.

Route Details

Health

GET /api/health

Returns service state plus vault metadata.

curl http://localhost:8080/api/health

Tasks

GET /api/tasks

Basic task listing with pagination only.

Query params:

  • limit (default 50, max 200)
  • offset (default 0)

Important:

  • Filtering params such as status, priority, tag, project, due_before, due_after, overdue, completed, archived, and sort are rejected on this endpoint with HTTP 400.
  • Use POST /api/tasks/query for filtering.

Example:

curl "http://localhost:8080/api/tasks?limit=25&offset=0"

Response fields:

  • data.tasks
  • data.pagination with total, offset, limit, hasMore
  • data.vault
  • data.note

POST /api/tasks

Create one task.

Required:

  • title

Common optional fields:

  • details, status, priority, due, scheduled
  • tags, contexts, projects
  • recurrence, timeEstimate
curl -X POST http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Review docs","priority":"high"}'

Returns HTTP 201 with created task data.

GET /api/tasks/:id

Get one task by path id.

  • :id must be URL-encoded task path.
curl "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md"

PUT /api/tasks/:id

Update task with partial payload.

curl -X PUT "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md" \
  -H "Content-Type: application/json" \
  -d '{"status":"in-progress"}'

DELETE /api/tasks/:id

Delete task file.

POST /api/tasks/:id/toggle-status

Toggle task status via configured workflow.

POST /api/tasks/:id/archive

Toggle archive state.

POST /api/tasks/:id/complete-instance

Complete recurring instance.

Request body:

  • Optional date (ISO string). If omitted, uses current date context.

POST /api/tasks/query

Advanced filtering.

Request body is a FilterQuery object. Root object is a group with:

  • type: "group"
  • id
  • conjunction: "and" | "or"
  • children (conditions or groups)

Optional top-level query options:

  • sortKey, sortDirection
  • groupKey, subgroupKey

Example:

{
  "type": "group",
  "id": "root",
  "conjunction": "and",
  "children": [
    {
      "type": "condition",
      "id": "c1",
      "property": "status",
      "operator": "is",
      "value": "open"
    }
  ],
  "sortKey": "due",
  "sortDirection": "asc"
}

Response:

  • data.tasks
  • data.total
  • data.filtered
  • data.vault

GET /api/filter-options

Returns filter options for UI builders.

GET /api/stats

Returns summary counts:

  • total, completed, active, overdue, archived, withTimeTracking

Time Tracking

POST /api/tasks/:id/time/start

Starts a new active time entry for that task.

POST /api/tasks/:id/time/start-with-description

Starts time tracking and writes description on the new active entry.

Request body:

{
  "description": "Implementation"
}

POST /api/tasks/:id/time/stop

Stops active time entry for that task.

GET /api/tasks/:id/time

Returns per-task time summary and entries.

GET /api/time/active

Returns currently active sessions across tasks.

Important:

  • Multiple active sessions can exist across different tasks.

GET /api/time/summary

Returns aggregate time summary.

Query params:

  • period (for example today, week, month, all)
  • from (ISO date)
  • to (ISO date)

Example:

curl "http://localhost:8080/api/time/summary?period=week"

Pomodoro

POST /api/pomodoro/start

Starts a session.

Optional request fields:

  • taskId (URL path of task)
  • duration (number)

POST /api/pomodoro/stop

Stops and resets current session.

POST /api/pomodoro/pause

Pauses running session.

POST /api/pomodoro/resume

Resumes paused session.

GET /api/pomodoro/status

Returns current state plus computed totals (totalPomodoros, currentStreak, totalMinutesToday).

GET /api/pomodoro/sessions

Returns history.

Query params:

  • limit
  • date (YYYY-MM-DD)

GET /api/pomodoro/stats

Returns stats for today or provided date.

Query params:

  • date (YYYY-MM-DD)

Calendars

GET /api/calendars

Returns provider connectivity overview and subscription counts.

GET /api/calendars/google

Returns Google provider details.

  • If disconnected, returns { "connected": false }.

GET /api/calendars/microsoft

Returns Microsoft provider details.

  • If disconnected, returns { "connected": false }.

GET /api/calendars/subscriptions

Returns ICS subscriptions with runtime fields such as lastFetched and lastError.

GET /api/calendars/events

Returns merged event list from connected providers and ICS subscriptions.

Query params:

  • start (ISO date/datetime)
  • end (ISO date/datetime)

Response includes:

  • events
  • total
  • sources (counts by provider)

Webhooks

POST /api/webhooks

Registers webhook.

Required fields:

  • url
  • events (non-empty array)

Optional fields:

  • id
  • secret
  • active
  • transformFile
  • corsHeaders

GET /api/webhooks

Lists registered webhooks. Stored secrets are not returned.

DELETE /api/webhooks/:id

Deletes webhook.

GET /api/webhooks/deliveries

Returns last 100 delivery records.

OpenAPI Docs

GET /api/docs

Returns OpenAPI JSON generated from registered controllers.

GET /api/docs/ui

Returns Swagger UI.

Errors

Common status codes:

  • 400 invalid request or invalid state
  • 401 missing/invalid bearer token (when auth token is configured)
  • 404 missing task/webhook/resource
  • 500 internal error

Security Notes

Current behavior:

  • CORS allows all origins (*).
  • Transport is HTTP only (no TLS).
  • Node server is started with server.listen(port) and does not explicitly bind to 127.0.0.1.

Practical guidance:

  • Set an auth token.
  • Treat API port as sensitive and keep it firewalled.
  • If you expose this port outside localhost, route through a trusted reverse proxy and TLS.

Troubleshooting

API unavailable

  1. Confirm API is enabled in settings.
  2. Confirm Obsidian is running.
  3. Confirm selected port is free.
  4. Reload plugin or restart Obsidian after changing API enable/port.

401 Authentication required

  1. Check token value.
  2. Check Bearer prefix.
  3. Remove whitespace around token.

Unexpected task list behavior

If you pass filters to GET /api/tasks, the endpoint returns 400 by design. Use POST /api/tasks/query.