things-api 0.1.0

REST API for Things 3 — expose your tasks over HTTP

Things API

REST API for Things 3 — expose your tasks over HTTP.

Things API reads directly from the Things SQLite database via things.py and writes back through the Things URL scheme. It runs as a lightweight FastAPI service on any Mac where Things is installed, giving you full programmatic access to your tasks from tools like n8n, curl, or any HTTP client.

Getting started

Requirements: macOS with Things 3 installed, Python 3.12+, and uv.

1. Clone and install

git clone https://github.com/jaydenk/things-api.git
cd things-api
uv venv
uv pip install -e .

2. Configure

cp env.example .env

Open .env and set your API token — this is the bearer token that authenticates every request:

THINGS_API_TOKEN=choose-a-secure-random-string

To enable write operations (creating, updating, completing todos), you also need a Things URL scheme auth token. To get one, open Things > Settings > General > Enable Things URLs and copy the token:

THINGS_AUTH_TOKEN=your-things-url-scheme-token

Without THINGS_AUTH_TOKEN, the API runs in read-only mode.

See docs/configuration.md for all configuration options.

3. Run

uv run things-api

The server starts on http://localhost:5225.

4. Try it

# Health check
curl http://localhost:5225/health \
  -H "Authorization: Bearer YOUR_TOKEN"

# List today's tasks
curl http://localhost:5225/today \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create a todo (requires THINGS_AUTH_TOKEN)
curl -X POST http://localhost:5225/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy milk", "when": "today"}'

To run the server persistently (auto-start at login, auto-restart on crash), see the deployment guide.

Endpoints overview

Every endpoint requires a valid Authorization: Bearer <token> header.

Resource	Endpoints	Description
Todos	GET POST PUT DELETE /todos	Full CRUD for todos
Projects	GET POST PUT DELETE /projects	Full CRUD for projects
Smart lists	GET /inbox /today /upcoming /anytime /someday /logbook	Read-only access to Things smart lists
Tags	GET /tags	List tags and items by tag
Areas	GET /areas	List areas
Search	GET /search /search/advanced	Full-text and filtered search
Health	GET /health	Service status and database connectivity

Note: DELETE on todos and projects is irreversible — it completes or cancels the item. Things 3 does not support true deletion.

See docs/api-reference.md for full endpoint details, request/response schemas, and query parameters.

Limitations

• macOS only — Things 3 is a Mac app. The API must run on the same machine.
• GUI session required for writes — Write operations invoke the Things URL scheme, which requires an active GUI session.
• No true deletion — DELETE endpoints complete or cancel items instead.

Further documentation

• Configuration reference — All environment variables and their defaults
• API reference — Full endpoint documentation with request/response details
• Deployment guide — Running as a launchd service, n8n integration
• Development guide — Setting up a dev environment, running tests
• Changelog — Version history

Licence

MIT