TaskNotesDocumentation
Open app

Obsidian plugin · 4.18.2

TaskNotes HTTP API

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

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
  • Bound to loopback (127.0.0.1) only, not the local network
  • Browser CORS requests are allowed only from loopback origins such as localhost, 127.0.0.1, and [::1]
  • Not available on mobile

Enable it under Settings → TaskNotes → Integrations → HTTP API in v4, or Settings → TaskNotes → Advanced → HTTP API in the v5 beta.

Base URL#

http://localhost:{PORT}

Default port is 8080.

Authentication#

Authentication is required for both HTTP API and MCP requests in TaskNotes 4.13.0 and later, including the v5 beta.

  • Send Authorization: Bearer <token> using the TaskNotes token from the HTTP API settings page described above.
  • If apiAuthToken is empty at startup, TaskNotes generates and saves a token before starting the server.
  • Clearing the token does not enable unauthenticated access; requests are rejected until a token is configured or generated at the next server start.
  • Existing clients that omitted authentication must be updated to send the token. Keep it private.

Token storage in the v5 beta#

In v4, the HTTP API token is stored in data.json. In v5, it moves to Obsidian Secret Storage on each device. Syncing or committing data.json does not share the v5 token. A synced device that starts after the token has been removed from data.json generates its own token and shows a notice. Copy that device's token into its API and MCP clients. See Synced devices.

Example:

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

Connecting Claude Desktop with MCP#

Use a TaskNotes API token, not a Claude/Anthropic API key. The local MCP endpoint uses bearer authentication, not OAuth registration.

  1. Open Settings → TaskNotes → Integrations in v4, or Advanced in the v5 beta, and enable HTTP API and MCP server.
  2. If the TaskNotes token is empty, restart Obsidian to generate one. An existing token can be reused; do not clear it unless you intend to replace it in all clients.
  3. Return to the same settings page and copy the generated token. Keep it private.
  4. In Claude Desktop, open Settings → Developer → Edit Config and add this entry, preserving any other MCP servers:
{
  "mcpServers": {
    "Tasknotes": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8080/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TASKNOTES_API_TOKEN"
      }
    }
  }
}

Replace YOUR_TASKNOTES_API_TOKEN with the token from TaskNotes, keeping the Bearer prefix. Change 8080 if you configured a different port. Node.js/npm must be installed so Claude can run npx.

  1. Fully quit and reopen Claude Desktop. Keep Obsidian running while using the tools.

If Claude reports Server Disconnected, first check that the bearer header contains the current TaskNotes token. A missing or rejected token can cause the client to attempt OAuth registration, which this endpoint does not provide. After replacing a token, update every client and restart Claude. Do not disable authentication as a workaround.

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/:id/materialize-occurrence
  • POST /api/tasks/query
  • GET /api/filter-options
  • GET /api/stats

Bases#

  • POST /api/bases/default-files/update

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, context, 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
  • Task objects include configured TaskNotes user fields in customProperties, keyed by their frontmatter property key.

POST /api/tasks#

Create one task.

Required:

  • title

Common optional fields:

  • details, status, priority, due, scheduled
  • tags, contexts, projects
  • recurrence, recurrence_anchor, timeEstimate, reminders
  • blockedBy

blockedBy accepts an array of dependency objects:

  • uid: link or identifier for the blocking task, such as [[Project setup]]
  • reltype: one of FINISHTOSTART, FINISHTOFINISH, STARTTOSTART, or STARTTOFINISH
  • gap: optional ISO 8601 duration, such as P1D

blocking is a read-only reverse relationship in API responses. To make a task block existing tasks, update those existing tasks' blockedBy fields.

curl -X POST http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Review docs","priority":"high","blockedBy":[{"uid":"[[Draft docs]]","reltype":"FINISHTOSTART"}]}'

Returns HTTP 201 with created task data.

GET /api/tasks/:id#

Get one task by path id.

  • :id must be URL-encoded task path.
  • Single-task reads include the task body in details.
  • Configured TaskNotes user fields are returned in customProperties, keyed by their frontmatter property key.
curl "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md"

PUT /api/tasks/:id#

Update task with partial payload.

Configured TaskNotes user fields can be updated either by their frontmatter property key or via customProperties.

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.

When the recurring parent uses materialized occurrence notes, this endpoint completes the matching occurrence note if one exists. If the parent is set to Create next after completion and no matching occurrence note exists yet, TaskNotes creates and completes that occurrence note instead of only recording a virtual complete_instances entry.

POST /api/tasks/:id/materialize-occurrence#

Create or return a materialized occurrence note for a recurring task date. This endpoint is idempotent for the same parent and date.

Request body:

  • Required date (ISO date string, for example 2026-06-01)

POST /api/tasks/query#

Advanced filtering.

Request body is a FilterQuery object. FilterQuery is still the supported advanced query shape for the HTTP API.

The 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"
}

Filter tasks by context:

{
  "type": "group",
  "id": "root",
  "conjunction": "and",
  "children": [
    {
      "type": "condition",
      "id": "context",
      "property": "contexts",
      "operator": "contains",
      "value": "@office"
    }
  ],
  "sortKey": "due",
  "sortDirection": "asc"
}

Filter active, unarchived tasks, similar to the default available-task view:

{
  "type": "group",
  "id": "root",
  "conjunction": "and",
  "children": [
    {
      "type": "condition",
      "id": "not-archived",
      "property": "archived",
      "operator": "is-not-checked"
    },
    {
      "type": "condition",
      "id": "not-completed",
      "property": "status.isCompleted",
      "operator": "is-not-checked"
    }
  ],
  "sortKey": "due",
  "sortDirection": "asc",
  "groupKey": "none"
}

Condition fields:

  • type: "condition"
  • id: any stable string for your client
  • property: a task property, such as title, status, priority, tags, contexts, projects, blockedBy, blocking, due, scheduled, completedDate, dateCreated, dateModified, archived, hasSubtasks, dependencies.isBlocked, dependencies.isBlocking, timeEstimate, recurrence, or status.isCompleted
  • operator: one of is, is-not, contains, does-not-contain, is-before, is-after, is-on-or-before, is-on-or-after, is-empty, is-not-empty, is-checked, is-not-checked, is-greater-than, is-less-than, is-greater-than-or-equal, or is-less-than-or-equal
  • value: required for comparison operators, omitted for empty/checked operators

For user-defined fields, use property: "user:<fieldId>".

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

Bases#

POST /api/bases/default-files/update#

Overwrite the configured default TaskNotes .base files with templates generated from the current TaskNotes settings. This is the same write operation as Settings -> TaskNotes -> Views & base files -> Update files and replaces manual edits in those configured default files.

curl -X POST http://localhost:8080/api/bases/default-files/update

Response fields:

  • data.created: default files created because they were missing
  • data.updated: existing default files overwritten with current templates
  • data.skipped: configured default files skipped

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.

Source: tasknotes.dev:content/obsidian/HTTP_API.mdView source