{"id":48409013,"url":"https://github.com/jaydenk/things-api","last_synced_at":"2026-04-06T05:01:10.978Z","repository":{"id":348838926,"uuid":"1200069831","full_name":"jaydenk/things-api","owner":"jaydenk","description":"REST API for Things 3 — expose your tasks over HTTP. Reads via things.py, writes via URL scheme.","archived":false,"fork":false,"pushed_at":"2026-04-03T03:11:25.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T11:48:25.011Z","etag":null,"topics":["automation","fastapi","gtd","macos","pypi","python","rest-api","task-management","things","things3"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/things-api/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaydenk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T02:18:16.000Z","updated_at":"2026-04-03T03:11:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"0222b58c-c693-4802-a05f-9c32884f981d","html_url":"https://github.com/jaydenk/things-api","commit_stats":null,"previous_names":["jaydenk/things-api"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jaydenk/things-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenk%2Fthings-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenk%2Fthings-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenk%2Fthings-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenk%2Fthings-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaydenk","download_url":"https://codeload.github.com/jaydenk/things-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenk%2Fthings-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31460105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","fastapi","gtd","macos","pypi","python","rest-api","task-management","things","things3"],"created_at":"2026-04-06T05:00:29.129Z","updated_at":"2026-04-06T05:01:10.968Z","avatar_url":"https://github.com/jaydenk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Things API\n\nREST API for [Things 3](https://culturedcode.com/things/) — expose your tasks over HTTP.\n\nThings 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.\n\n## Getting started\n\n**Requirements:** macOS with [Things 3](https://culturedcode.com/things/) installed and Python 3.12+.\n\n### 1. Install\n\nRun directly with [`uvx`](https://docs.astral.sh/uv/) (no install needed):\n\n```sh\nuvx things-api\n```\n\nOr install with pip:\n\n```sh\npip install things-api\n```\n\nOr clone the repo for development:\n\n```sh\ngit clone https://github.com/jaydenk/things-api.git\ncd things-api\nuv venv \u0026\u0026 uv pip install -e .\n```\n\n### 2. Configure\n\nRun the setup wizard:\n\n```sh\nthings-api init\n```\n\nThis 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.\n\nSee [docs/configuration.md](docs/configuration.md) for all configuration options.\n\n### 3. Run\n\n```sh\nthings-api\n```\n\nOverride settings on the fly:\n\n```sh\nthings-api --token my-token --port 8080\n```\n\nThe server starts on `http://localhost:5225` by default.\n\n### 4. Try it\n\n```sh\n# Health check\ncurl http://localhost:5225/health \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# List today's tasks\ncurl http://localhost:5225/today \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Create a todo (requires THINGS_AUTH_TOKEN)\ncurl -X POST http://localhost:5225/todos \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\": \"Buy milk\", \"when\": \"today\"}'\n```\n\nTo run the server persistently (auto-start at login, auto-restart on crash), see the [deployment guide](docs/deployment.md).\n\n## Endpoints overview\n\nEvery endpoint requires a valid `Authorization: Bearer \u003ctoken\u003e` header.\n\n| Resource | Endpoints | Description |\n|---|---|---|\n| **Todos** | `GET` `POST` `PUT` `DELETE` `/todos` | Full CRUD for todos |\n| **Projects** | `GET` `POST` `PUT` `DELETE` `/projects` | Full CRUD for projects |\n| **Smart lists** | `GET` `/inbox` `/today` `/upcoming` `/anytime` `/someday` `/logbook` | Read-only access to Things smart lists |\n| **Tags** | `GET` `/tags` | List tags and items by tag |\n| **Areas** | `GET` `/areas` | List areas |\n| **Search** | `GET` `/search` `/search/advanced` | Full-text and filtered search |\n| **Health** | `GET` `/health` | Service status and database connectivity |\n\n\u003e **Note:** `DELETE` on todos and projects is **irreversible** — it completes or cancels the item. Things 3 does not support true deletion.\n\nSee [docs/api-reference.md](docs/api-reference.md) for full endpoint details, request/response schemas, and query parameters.\n\n## Limitations\n\n- **macOS only** — Things 3 is a Mac app. The API must run on the same machine.\n- **GUI session required for writes** — Write operations invoke the Things URL scheme, which requires an active GUI session.\n- **No true deletion** — `DELETE` endpoints complete or cancel items instead.\n\n## Further documentation\n\n- [Configuration reference](docs/configuration.md) — All environment variables and their defaults\n- [API reference](docs/api-reference.md) — Full endpoint documentation with request/response details\n- [Deployment guide](docs/deployment.md) — Running as a launchd service, n8n integration\n- [Development guide](docs/development.md) — Setting up a dev environment, running tests\n- [Changelog](CHANGELOG.md) — Version history\n\n## Licence\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaydenk%2Fthings-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaydenk%2Fthings-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaydenk%2Fthings-api/lists"}