| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [View Raw Code] [Original HTTPS Page] |
The TaskNotes HTTP API provides local HTTP access to tasks, time tracking, pomodoro, calendars, webhooks, and NLP parsing.
Enable it in Settings -> TaskNotes -> Integrations -> HTTP API.
http://localhost:{PORT}
Default port is 8080.
Authentication is required for both HTTP API and MCP requests.
Example:
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/healthTaskNotes 4.13.0 and later require a TaskNotes API token, not a Claude/Anthropic API key. The local MCP endpoint uses bearer authentication, not OAuth registration.
{
"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. This configuration requires Node.js/npm so Claude can run npx.
If Claude reports Server Disconnected, or mcp-remote fails in registerClient/OAuth registration, 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 changing the token in TaskNotes, update every client and restart Claude. Do not disable authentication as a workaround.
Success:
{
"success": true,
"data": {}
}Error:
{
"success": false,
"error": "Error message"
}See docs/webhooks.md for event and transform details.
Returns service state plus vault metadata.
curl http://localhost:8080/api/healthBasic task listing with pagination only.
Query params:
Important:
Example:
curl "http://localhost:8080/api/tasks?limit=25&offset=0"Response fields:
Create one task.
Required:
Common optional fields:
blockedBy accepts an array of dependency objects:
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 one task by path id.
curl "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md"Update task with partial payload.
Configured TaskNotes user fields can be updated either by their frontmatter property key or via customProperties.
Sending an empty array for contexts or blockedBy clears the corresponding frontmatter field.
curl -X PUT "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md" \
-H "Content-Type: application/json" \
-d '{"status":"in-progress"}'Delete task file.
Toggle task status via configured workflow.
Toggle archive state.
Complete recurring instance.
Request body:
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.
Create or return a materialized occurrence note for a recurring task date. This endpoint is idempotent for the same parent and date.
Request body:
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:
Optional top-level query options:
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:
For user-defined fields, the canonical property is user:<fieldId>. Queries also accept user:<frontmatter-key>, user.<fieldId>, and user.<frontmatter-key>, including in sortKey and groupKey. For example, a field with ID field_1234567890 and key my-custom-field can be queried with either user:field_1234567890 or user:my-custom-field. Bare custom keys such as my-custom-field are not supported.
GET /api/filter-options returns each configured field in userProperties, including its canonical id, accepted aliases, frontmatterKey, and supportedOperators. Canonical IDs take precedence if a field's ID collides with another field's key.
External queries must contain complete, valid conditions. Unknown properties, invalid operators, incomplete conditions, and invalid sort/group keys return HTTP 400, even if the vault is empty or another AND/OR branch would short-circuit evaluation. A valid query with no matches remains a successful response with an empty task list.
The MCP tool tasknotes_query_tasks uses the same validation and custom-field aliases. Invalid queries return a tool result with isError: true; valid queries with no matches remain successful (for an ungrouped query, {"all":[]}). Use tasknotes_get_filter_options to discover fields before querying them.
Response:
Returns filter options for UI builders.
Returns summary counts:
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/updateResponse fields:
Starts a new active time entry for that task.
Starts time tracking and writes description on the new active entry.
Request body:
{
"description": "Implementation"
}Stops active time entry for that task.
Returns per-task time summary and entries.
Returns currently active sessions across tasks.
Important:
Returns aggregate time summary.
Query params:
Example:
curl "http://localhost:8080/api/time/summary?period=week"Starts a session.
Optional request fields:
Stops and resets current session.
Pauses running session.
Resumes paused session.
Returns current state plus computed totals (totalPomodoros, currentStreak, totalMinutesToday).
Returns history.
Query params:
Returns stats for today or provided date.
Query params:
Returns provider connectivity overview and subscription counts.
Returns Google provider details.
Returns Microsoft provider details.
Returns ICS subscriptions with runtime fields such as lastFetched and lastError.
Returns merged event list from connected providers and ICS subscriptions.
Query params:
Response includes:
Registers webhook.
Required fields:
Optional fields:
Lists registered webhooks. Stored secrets are not returned.
Deletes webhook.
Returns last 100 delivery records.
Returns OpenAPI JSON generated from registered controllers.
Returns Swagger UI.
Common status codes:
Current behavior:
Practical guidance:
If you pass filters to GET /api/tasks, the endpoint returns 400 by design. Use POST /api/tasks/query.
| Back | FazBrowse Home | New Git URL |