things-api 0.3.1

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 and Python 3.12+.

1. Install

Run directly with uvx (no install needed):

uvx things-api

Or install with pip:

pip install things-api

Or clone the repo for development:

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

2. Configure

Run the setup wizard:

things-api init

This generates an API token, checks your Things URL scheme settings, and writes the config to ~/.config/things-api/config. If you skip this step, the wizard runs automatically on first launch.

See docs/configuration.md for all configuration options.

3. Run

things-api

Override settings on the fly:

things-api --token my-token --port 8080

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

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