things-api 0.1.0__tar.gz

things_api-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.env
+TODO.md

things_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-04-03
+
+### Added
+
+- FastAPI REST API for Things 3 with bearer token authentication
+- Full CRUD for todos and projects via Things URL scheme
+- Read-only endpoints for smart lists (inbox, today, upcoming, anytime, someday, logbook)
+- Tag and area listing endpoints
+- Full-text and advanced filtered search
+- Health endpoint with database connectivity check
+- Configuration via environment variables and `.env` file
+- Rate limiting on failed authentication attempts (10 per minute per IP)
+- Timing-safe token comparison and `SecretStr` for token storage
+- launchd plist template for running as a persistent service
+- 69 unit tests covering auth, config, services, routers, and rate limiting
+
+### Security
+
+- Bearer tokens stored as `SecretStr` — never exposed in logs, repr, or stack traces
+- Auth token redacted in log output (both raw and URL-encoded forms)
+- Subprocess stderr logged server-side only — never returned to API consumers
+- Swagger/ReDoc UI disabled to prevent schema reconnaissance

things_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2026 Jayden Kerr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

things_api-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: things-api
+Version: 0.1.0
+Summary: REST API for Things 3 — expose your tasks over HTTP
+Project-URL: Homepage, https://github.com/jaydenk/things-api
+Project-URL: Documentation, https://github.com/jaydenk/things-api/tree/main/docs
+Project-URL: Issues, https://github.com/jaydenk/things-api/issues
+Project-URL: Changelog, https://github.com/jaydenk/things-api/blob/main/CHANGELOG.md
+Author: Jayden Kerr
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,gtd,rest,tasks,things,things3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.135
+Requires-Dist: pydantic-settings<3,>=2.13
+Requires-Dist: things-py<2,>=1.0
+Requires-Dist: uvicorn[standard]<1,>=0.34
+Provides-Extra: test
+Requires-Dist: httpx>=0.28; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Things API
+
+REST API for [Things 3](https://culturedcode.com/things/) — expose your tasks over HTTP.
+
+Things API reads directly from the Things SQLite database via [things.py](https://github.com/thingsapi/things.py) and writes back through the [Things URL scheme](https://culturedcode.com/things/support/articles/2803573/). 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](https://n8n.io/), [curl](https://curl.se/), or any HTTP client.
+
+## Getting started
+
+**Requirements:** macOS with [Things 3](https://culturedcode.com/things/) installed, Python 3.12+, and [uv](https://docs.astral.sh/uv/).
+
+### 1. Clone and install
+
+```sh
+git clone https://github.com/jaydenk/things-api.git
+cd things-api
+uv venv
+uv pip install -e .
+```
+
+### 2. Configure
+
+```sh
+cp env.example .env
+```
+
+Open `.env` and set your API token — this is the bearer token that authenticates every request:
+
+```dotenv
+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:
+
+```dotenv
+THINGS_AUTH_TOKEN=your-things-url-scheme-token
+```
+
+Without `THINGS_AUTH_TOKEN`, the API runs in **read-only mode**.
+
+See [docs/configuration.md](docs/configuration.md) for all configuration options.
+
+### 3. Run
+
+```sh
+uv run things-api
+```
+
+The server starts on `http://localhost:5225`.
+
+### 4. Try it
+
+```sh
+# 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](docs/deployment.md).
+
+## 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](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](docs/configuration.md) — All environment variables and their defaults
+- [API reference](docs/api-reference.md) — Full endpoint documentation with request/response details
+- [Deployment guide](docs/deployment.md) — Running as a launchd service, n8n integration
+- [Development guide](docs/development.md) — Setting up a dev environment, running tests
+- [Changelog](CHANGELOG.md) — Version history
+
+## Licence
+
+[MIT](./LICENSE)

things_api-0.1.0/README.md

@@ -0,0 +1,104 @@
+# Things API
+
+REST API for [Things 3](https://culturedcode.com/things/) — expose your tasks over HTTP.
+
+Things API reads directly from the Things SQLite database via [things.py](https://github.com/thingsapi/things.py) and writes back through the [Things URL scheme](https://culturedcode.com/things/support/articles/2803573/). 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](https://n8n.io/), [curl](https://curl.se/), or any HTTP client.
+
+## Getting started
+
+**Requirements:** macOS with [Things 3](https://culturedcode.com/things/) installed, Python 3.12+, and [uv](https://docs.astral.sh/uv/).
+
+### 1. Clone and install
+
+```sh
+git clone https://github.com/jaydenk/things-api.git
+cd things-api
+uv venv
+uv pip install -e .
+```
+
+### 2. Configure
+
+```sh
+cp env.example .env
+```
+
+Open `.env` and set your API token — this is the bearer token that authenticates every request:
+
+```dotenv
+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:
+
+```dotenv
+THINGS_AUTH_TOKEN=your-things-url-scheme-token
+```
+
+Without `THINGS_AUTH_TOKEN`, the API runs in **read-only mode**.
+
+See [docs/configuration.md](docs/configuration.md) for all configuration options.
+
+### 3. Run
+
+```sh
+uv run things-api
+```
+
+The server starts on `http://localhost:5225`.
+
+### 4. Try it
+
+```sh
+# 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](docs/deployment.md).
+
+## 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](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](docs/configuration.md) — All environment variables and their defaults
+- [API reference](docs/api-reference.md) — Full endpoint documentation with request/response details
+- [Deployment guide](docs/deployment.md) — Running as a launchd service, n8n integration
+- [Development guide](docs/development.md) — Setting up a dev environment, running tests
+- [Changelog](CHANGELOG.md) — Version history
+
+## Licence
+
+[MIT](./LICENSE)

things_api-0.1.0/com.things-api.server.plist

@@ -0,0 +1,58 @@
+<!--
+  Things API launchd agent
+
+  Install:
+    1. Edit this file — set WorkingDirectory and ProgramArguments paths
+    2. Ensure your .env file exists in the working directory with THINGS_API_TOKEN set
+    3. cp com.things-api.server.plist ~/Library/LaunchAgents/
+    4. launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.things-api.server.plist
+
+  Uninstall:
+    launchctl bootout gui/$(id -u)/com.things-api.server
+    rm ~/Library/LaunchAgents/com.things-api.server.plist
+-->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>com.things-api.server</string>
+
+	<!-- Working directory — the server reads .env from here -->
+	<key>WorkingDirectory</key>
+	<string>/path/to/things-api</string>
+
+	<!--
+	  Option A: Run from local source (development / pre-PyPI)
+	  Uses uv run to execute from the project directory.
+	  Replace /path/to/uv with the output of: which uv
+	-->
+	<key>ProgramArguments</key>
+	<array>
+		<string>/path/to/uv</string>
+		<string>run</string>
+		<string>things-api</string>
+	</array>
+
+	<!--
+	  Option B: Run from PyPI (after publishing)
+	  Uncomment this block and comment out Option A above.
+	  Replace /path/to/uvx with the output of: which uvx
+
+	<key>ProgramArguments</key>
+	<array>
+		<string>/path/to/uvx</string>
+		<string>things-api</string>
+	</array>
+	-->
+
+	<key>KeepAlive</key>
+	<true/>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>StandardOutPath</key>
+	<string>/tmp/things-api.log</string>
+	<key>StandardErrorPath</key>
+	<string>/tmp/things-api.log</string>
+</dict>
+</plist>

things_api-0.1.0/docs/api-reference.md

@@ -0,0 +1,207 @@
+# API Reference
+
+Every endpoint requires a valid `Authorization: Bearer <token>` header.
+
+## Health
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Returns service status, database readability, and whether write operations are available |
+
+**Response:**
+
+```json
+{
+  "status": "healthy",
+  "read": true,
+  "write": true
+}
+```
+
+The `status` field is `"healthy"` when the database is readable, or `"degraded"` if it cannot be accessed.
+
+## Todos
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/todos` | List all incomplete todos |
+| `GET` | `/todos/{id}` | Get a specific todo by UUID |
+| `POST` | `/todos` | Create a new todo |
+| `PUT` | `/todos/{id}` | Update an existing todo |
+| `DELETE` | `/todos/{id}` | Complete or cancel a todo (**irreversible**) |
+
+### Query parameters for `GET /todos`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `project_id` | string | Filter by project UUID |
+| `area_id` | string | Filter by area UUID |
+| `tag` | string | Filter by tag name |
+| `include_checklist` | bool | Include checklist items in the response |
+
+### `POST /todos` — Create
+
+Returns `202 Accepted` with the submitted title. The Things URL scheme does not return the UUID of the created item.
+
+**Request body:**
+
+| Field | Required | Type | Description |
+|---|---|---|---|
+| `title` | **Yes** | string | Todo title |
+| `notes` | No | string | Notes/description |
+| `when` | No | string | Schedule: `"today"`, `"tomorrow"`, `"evening"`, `"someday"`, or a date string |
+| `deadline` | No | string | Deadline date (YYYY-MM-DD) |
+| `tags` | No | string[] | Tag names to apply |
+| `checklist_items` | No | string[] | Checklist items to add |
+| `list_id` | No | string | Project UUID to add the todo to |
+| `list_title` | No | string | Project title to add the todo to |
+| `heading` | No | string | Heading name within the project |
+| `heading_id` | No | string | Heading UUID within the project |
+
+### `PUT /todos/{id}` — Update
+
+Returns the updated todo if read-back succeeds, or `202 Accepted` if verification times out.
+
+**Request body** (all fields optional):
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | string | New title |
+| `notes` | string | Replace notes |
+| `prepend_notes` | string | Prepend to existing notes |
+| `append_notes` | string | Append to existing notes |
+| `when` | string | Reschedule |
+| `deadline` | string | New deadline (YYYY-MM-DD) |
+| `tags` | string[] | Replace tags |
+| `add_tags` | string[] | Add tags without removing existing ones |
+| `checklist_items` | string[] | Replace checklist |
+| `prepend_checklist_items` | string[] | Prepend to checklist |
+| `append_checklist_items` | string[] | Append to checklist |
+| `list_id` | string | Move to project by UUID |
+| `list_title` | string | Move to project by title |
+| `heading` | string | Move to heading by name |
+| `heading_id` | string | Move to heading by UUID |
+
+### `DELETE /todos/{id}` — Complete or cancel
+
+**This action is irreversible.** Things 3 does not support true deletion.
+
+**Request body** (optional):
+
+```json
+{"action": "complete"}
+```
+
+or
+
+```json
+{"action": "cancel"}
+```
+
+Defaults to `"complete"` if no body is provided.
+
+## Projects
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/projects` | List all projects |
+| `GET` | `/projects/{id}` | Get a project by UUID |
+| `POST` | `/projects` | Create a new project |
+| `PUT` | `/projects/{id}` | Update an existing project |
+| `DELETE` | `/projects/{id}` | Complete or cancel a project (**irreversible**) |
+
+### `POST /projects` — Create
+
+Returns `202 Accepted`. Request body:
+
+| Field | Required | Type | Description |
+|---|---|---|---|
+| `title` | **Yes** | string | Project title |
+| `notes` | No | string | Notes/description |
+| `when` | No | string | Schedule |
+| `deadline` | No | string | Deadline date (YYYY-MM-DD) |
+| `tags` | No | string[] | Tag names |
+| `area_id` | No | string | Area UUID |
+| `area_title` | No | string | Area title |
+| `todos` | No | string[] | Initial todo titles to create in the project |
+
+### `PUT /projects/{id}` — Update
+
+All fields optional. Same pattern as todo updates (`notes`, `prepend_notes`, `append_notes`, `when`, `deadline`, `tags`, `add_tags`, `area_id`, `area_title`).
+
+### `DELETE /projects/{id}` — Complete or cancel
+
+Same semantics as todo DELETE. **Irreversible.**
+
+## Smart lists
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/inbox` | Inbox todos |
+| `GET` | `/today` | Today's todos |
+| `GET` | `/upcoming` | Upcoming scheduled todos |
+| `GET` | `/anytime` | Anytime todos |
+| `GET` | `/someday` | Someday todos |
+| `GET` | `/logbook` | Completed todos |
+
+### Query parameters for `GET /logbook`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `period` | string | Time period, e.g. `3d` (3 days), `1w` (1 week), `2m` (2 months) |
+| `limit` | int | Maximum number of items to return |
+
+## Areas
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/areas` | List all areas |
+
+### Query parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `include_items` | bool | Include todos and projects within each area |
+
+## Tags
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/tags` | List all tags |
+| `GET` | `/tags/{tag}/items` | Get all items with a specific tag |
+
+### Query parameters for `GET /tags`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `include_items` | bool | Include tagged items in the response |
+
+## Search
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/search?q=` | Full-text search across todos |
+| `GET` | `/search/advanced` | Filtered search with multiple criteria |
+
+### Query parameters for `GET /search/advanced`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `status` | enum | `incomplete`, `completed`, or `canceled` |
+| `tag` | string | Filter by tag name |
+| `area` | string | Filter by area UUID |
+| `type` | enum | `to-do`, `project`, or `heading` |
+| `start_date` | string | Start date (YYYY-MM-DD) |
+| `deadline` | string | Deadline date (YYYY-MM-DD) |
+| `last` | string | Time period, e.g. `7d`, `2w`, `1m` |
+
+## Error responses
+
+| Status | Meaning |
+|---|---|
+| `401 Unauthorized` | Missing or invalid bearer token |
+| `404 Not Found` | Todo or project not found by UUID |
+| `422 Unprocessable Entity` | Invalid request body |
+| `429 Too Many Requests` | Rate limit exceeded (too many failed auth attempts) |
+| `500 Internal Server Error` | Write operation failed |
+| `503 Service Unavailable` | Write endpoints called without `THINGS_AUTH_TOKEN`, or database not accessible |

things_api-0.1.0/docs/configuration.md

@@ -0,0 +1,32 @@
+# Configuration
+
+All settings are read from environment variables or a `.env` file in the working directory. Copy `env.example` to `.env` and adjust as needed.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `THINGS_API_HOST` | No | `0.0.0.0` | Address the server binds to |
+| `THINGS_API_PORT` | No | `5225` | Port the server listens on |
+| `THINGS_API_TOKEN` | **Yes** | — | Bearer token used to authenticate every request. The server refuses to start without it. |
+| `THINGS_AUTH_TOKEN` | No | — | Things URL scheme auth token — enables write operations (create, update, complete, cancel) |
+| `THINGS_DB_PATH` | No | Auto-detected | Override the path to the Things SQLite database. By default, `things.py` finds it automatically. |
+| `THINGS_VERIFY_TIMEOUT` | No | `0.5` | Seconds to wait after a write before reading back the result for verification |
+
+## Read-only vs read-write mode
+
+Without `THINGS_AUTH_TOKEN`, the API runs in **read-only mode**. All `GET` endpoints work normally, but `POST`, `PUT`, and `DELETE` return `503 Service Unavailable`.
+
+To enable write operations:
+
+1. Open **Things 3**
+2. Go to **Settings > General > Enable Things URLs**
+3. Copy the auth token
+4. Set `THINGS_AUTH_TOKEN` in your `.env` file
+
+## Security notes
+
+- `THINGS_API_TOKEN` is stored internally as a `SecretStr` — it will not appear in logs, stack traces, or error messages.
+- All authentication uses timing-safe comparison to prevent timing attacks.
+- Failed authentication attempts are rate-limited (10 per minute per IP).
+- The Swagger/ReDoc documentation UI is disabled. The API schema is not exposed at `/docs` or `/redoc`.

things_api-0.1.0/docs/deployment.md

@@ -0,0 +1,87 @@
+# Deployment
+
+These instructions assume you've already completed the [Getting Started](../README.md#getting-started) steps — the repo is cloned, dependencies are installed, and your `.env` file is configured.
+
+## Running as a launchd service
+
+A launchd agent keeps Things API running in the background. It starts automatically at login and restarts if it crashes.
+
+### 1. Edit the plist template
+
+Open `com.things-api.server.plist` in the project root and set two paths:
+
+**`WorkingDirectory`** — the absolute path to your cloned `things-api` directory. This is where the server looks for your `.env` file.
+
+```xml
+<key>WorkingDirectory</key>
+<string>/Users/yourname/things-api</string>
+```
+
+**`ProgramArguments`** — the absolute path to `uv`. Find it with `which uv`.
+
+```xml
+<key>ProgramArguments</key>
+<array>
+    <string>/opt/homebrew/bin/uv</string>
+    <string>run</string>
+    <string>things-api</string>
+</array>
+```
+
+> **Note:** launchd does not inherit your shell's `PATH`, so you must use the full path to `uv`.
+
+### 2. Install and load
+
+```sh
+cp com.things-api.server.plist ~/Library/LaunchAgents/
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.things-api.server.plist
+```
+
+### 3. Verify
+
+```sh
+curl -s http://localhost:5225/health -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+You should see `{"status":"healthy","read":true,...}`.
+
+### 4. Stop and unload
+
+```sh
+launchctl bootout gui/$(id -u)/com.things-api.server
+```
+
+To reload after editing the plist, bootout then bootstrap again.
+
+### Logs
+
+```sh
+tail -f /tmp/things-api.log
+```
+
+### How it works
+
+- **`WorkingDirectory`** — launchd starts the process in your project directory, so `pydantic-settings` automatically loads the `.env` file. No tokens need to be hardcoded in the plist.
+- **`KeepAlive: true`** — restarts the process if it crashes.
+- **`RunAtLoad: true`** — starts when you log in.
+
+## n8n integration
+
+Things API works well as a backend for [n8n](https://n8n.io/) workflows. Use an **HTTP Request** node:
+
+| Setting | Value |
+|---|---|
+| Method | `GET` / `POST` / `PUT` / `DELETE` |
+| URL | `http://<host>:5225/today` (or any endpoint) |
+| Authentication | Header Auth |
+| Header Name | `Authorization` |
+| Header Value | `Bearer YOUR_TOKEN_HERE` |
+| Response Format | JSON |
+
+For write operations, set the body content type to JSON and pass the relevant fields (e.g. `{"title": "New task", "when": "today"}`).
+
+## Network access
+
+By default, the server binds to `0.0.0.0`, making it accessible on all network interfaces. To restrict to localhost only, set `THINGS_API_HOST=127.0.0.1` in your `.env`.
+
+For remote access (e.g. from another machine on your network or via [Tailscale](https://tailscale.com/)), the default `0.0.0.0` binding works — just ensure the port (default `5225`) is accessible and use your machine's IP or Tailscale hostname in requests.