callumalpass_tasknotes/docs/HTTP_API.md

TaskNotes HTTP API

The TaskNotes HTTP API allows external applications to interact with your TaskNotes data. This enables powerful integrations with browsers, automation tools, mobile apps, and custom scripts.

Quick Start

1. Enable API: Go to TaskNotes Settings → HTTP API tab (desktop only)
2. Configure: Set port (default 8080) and optional auth token
3. Restart: Restart Obsidian to start the server
4. Test: curl http://localhost:8080/api/health

Authentication

Optional Bearer Token

# Set token in settings, then use in requests:
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/tasks

No Authentication

If no token is configured, all requests are allowed from localhost.

Base URL

http://localhost:{PORT}/api

Default port is 8080 (configurable in settings).

Response Format

All endpoints return JSON in this format:

{
  "success": true,
  "data": { /* response data */ },
  "message": "optional success message"
}

Error responses:

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

Endpoints

Health Check

GET /api/health

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "timestamp": "2025-08-12T10:30:00.000Z"
  }
}

Tasks

List Tasks

GET /api/tasks

Query Parameters:

• status - Filter by status (e.g., "open", "completed")
• priority - Filter by priority (e.g., "High", "Normal")
• project - Filter by project name (partial match)
• tag - Filter by tag (partial match)
• overdue - "true" for overdue tasks only
• completed - "true" or "false"
• archived - "true" or "false"
• due_before - ISO date (e.g., "2025-08-15")
• due_after - ISO date
• sort - Field to sort by (e.g., "due:asc", "priority:desc")
• limit - Max number of results
• offset - Skip this many results

Examples:

# All active tasks
curl "http://localhost:8080/api/tasks?completed=false&archived=false"

# High priority overdue tasks
curl "http://localhost:8080/api/tasks?priority=High&overdue=true"

# Tasks due this week, sorted by due date
curl "http://localhost:8080/api/tasks?due_before=2025-08-19&sort=due:asc"

Response:

{
  "success": true,
  "data": {
    "tasks": [
      {
        "path": "TaskNotes/Tasks/sample-task.md",
        "title": "Review quarterly budget",
        "status": "open",
        "priority": "High",
        "due": "2025-08-15",
        "scheduled": "2025-08-14",
        "tags": ["work", "finance"],
        "projects": ["[[Q3 Planning]]"],
        "contexts": ["@office"],
        "dateCreated": "2025-08-10T09:00:00.000Z",
        "dateModified": "2025-08-10T09:00:00.000Z"
      }
    ],
    "total": 150,
    "filtered": 1
  }
}

Create Task

POST /api/tasks

Request Body:

{
  "title": "New task title",
  "priority": "High",
  "status": "open",
  "due": "2025-08-15",
  "scheduled": "2025-08-14",
  "tags": ["email", "urgent"],
  "projects": ["[[Work Project]]"],
  "contexts": ["@computer"],
  "notes": "Additional task description",
  "timeEstimate": 60
}

Required Fields:

• title - Task title (max 200 characters)

Optional Fields:

• priority - Task priority
• status - Task status
• due - Due date (ISO format)
• scheduled - Scheduled date (ISO format)
• tags - Array of tag strings
• projects - Array of project links
• contexts - Array of context strings
• notes - Task description/notes
• timeEstimate - Estimated time in minutes

Get Single Task

GET /api/tasks/{id}

Where {id} is the task file path (URL-encoded).

Update Task

PUT /api/tasks/{id}

Request Body: Same format as create task, with partial updates supported.

Delete Task

DELETE /api/tasks/{id}

Time Tracking

Start Time Tracking

POST /api/tasks/{id}/time/start

Stop Time Tracking

POST /api/tasks/{id}/time/stop

Task Actions

Toggle Status

POST /api/tasks/{id}/toggle-status

Toggles between open/completed status.

Toggle Archive

POST /api/tasks/{id}/archive

Archives or unarchives the task.

Complete Recurring Instance

POST /api/tasks/{id}/complete-instance

Request Body:

{
  "date": "2025-08-12"
}

Advanced Queries

Query Tasks

POST /api/tasks/query

Request Body: Advanced FilterQuery object (see TaskNotes FilterQuery documentation).

Get Filter Options

GET /api/filter-options

Returns available tags, projects, statuses, and priorities for building filter UIs.

Statistics

Get Task Statistics

GET /api/stats

Response:

{
  "success": true,
  "data": {
    "total": 245,
    "completed": 189,
    "active": 45,
    "overdue": 8,
    "archived": 11,
    "withTimeTracking": 67
  }
}

Integration Examples

Browser Bookmarklet

javascript:(function(){
  const title = document.title;
  const url = window.location.href;
  
  fetch('http://localhost:8080/api/tasks', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      title: `Review: ${title}`,
      tags: ['web'],
      notes: `Source: ${url}`
    })
  }).then(r => r.json()).then(d => {
    alert(d.success ? 'Task created!' : 'Error: ' + d.error);
  });
})();

Python Script

import requests

def create_task(title, **kwargs):
    response = requests.post('http://localhost:8080/api/tasks', 
        json={'title': title, **kwargs})
    return response.json()

# Create task from command line
task = create_task("Call dentist", priority="High", due="2025-08-15")
print(f"Created task: {task['data']['title']}")

Automation (Zapier/IFTTT)

# Webhook URL for automation services
curl -X POST http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"{{trigger.subject}}", "tags":["email"], "notes":"{{trigger.body}}"}'

Error Handling

Common Errors

• 400 Bad Request - Invalid request data
• 401 Unauthorized - Invalid or missing auth token
• 404 Not Found - Task not found
• 500 Internal Server Error - Server error

Rate Limiting

No rate limiting currently implemented. Use responsibly.

CORS

CORS is enabled for all origins (*). API is intended for localhost use only.

Security Notes

• Localhost Only: API server only accepts connections from localhost
• Desktop Only: API is not available on mobile platforms
• Optional Auth: Bearer token authentication is optional but recommended
• No HTTPS: Traffic is unencrypted (localhost only)

Troubleshooting

API Not Starting

1. Check that API is enabled in settings
2. Ensure port is not in use by another application
3. Try different port (1024-65535)
4. Check Obsidian console for errors

Connection Refused

1. Verify API is enabled and Obsidian is running
2. Check correct port number
3. Ensure using http:// not https://
4. Try 127.0.0.1 instead of localhost

Authentication Errors

1. Verify token matches exactly (case-sensitive)
2. Include Bearer prefix in Authorization header
3. Check for trailing spaces in token

Development

API Versioning

Current version: 1.0

Future versions will maintain backwards compatibility where possible.

Feature Requests

Submit feature requests to the TaskNotes repository with the api label.

Contributing

See the main TaskNotes repository for contribution guidelines.