https://github.com/disrupted/things-cloud-api
(WIP) Unofficial Python client for Things Cloud
https://github.com/disrupted/things-cloud-api
api python reverse-engineering things3
Last synced: 12 months ago
JSON representation
(WIP) Unofficial Python client for Things Cloud
- Host: GitHub
- URL: https://github.com/disrupted/things-cloud-api
- Owner: disrupted
- License: gpl-3.0
- Created: 2021-06-14T19:56:16.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-11T15:44:50.000Z (about 1 year ago)
- Last Synced: 2025-04-01T19:03:24.231Z (12 months ago)
- Topics: api, python, reverse-engineering, things3
- Language: Python
- Homepage:
- Size: 403 KB
- Stars: 32
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Things Cloud Python client
> work in progress, expect breaking changes
Things is an excellent to-do manager for Apple devices, specifically the Mac, iPad, iPhone and Watch. Unfortunately there is no support outside these devices. Like many other users, I encountered this limitation after spending years using Things daily to plan nearly every aspect of my life and work.
> "A life without Things is possible, but pointless." — Loriot (German humorist)
This is an attempt of recreating some basic functionality Things Cloud has to offer, to help automate some recurring tasks (e.g. inside of Home Assistant).
Since there's no documentation, I've been analyzing the requests made by the Mac app. The exchanged data is often difficult to understand, because none of the fields use clear names. So far, figuring out the meaning of the to-do item fields, has been a mixed success. I was able to document some fields, while others remain a mystery.
Contributions are welcome to translate the rest of the fields.
## Usage
```python
from things_cloud import ThingsClient
from things_cloud.api.account import Account, Credentials
from things_cloud.models import TodoItem
EMAIL = os.environ["THINGS_EMAIL"]
PASSWORD = os.environ["THINGS_PASSWORD"]
credentials = Credentials(email=EMAIL, password=PASSWORD)
account = Account.login(credentials)
things = ThingsClient(account)
# create a new project
project = TodoItem(title="Things Cloud Project").as_project()
# push to Things Cloud
things.commit(project)
# create a todo inside project
todo = TodoItem(title="Try out Things Cloud")
todo.project = project
things.commit(todo)
# schedule for today
todo.today()
things.commit(todo)
```
## Example
See [main.py](./main.py).
Pass your Things Cloud credentials as environment examples to run the example
```sh
THINGS_EMAIL=your-email@example.com THINGS_PASSWORD=your-password uv run main.py
```
### Progress
- [x] Todos
- [x] create
- [x] edit
- [ ] list
- [ ] note
- [x] Projects
- [x] create
- [x] edit
- [ ] Areas
- [ ] Today
- [ ] Inbox
### Similar projects
- @nicolai86's Go [`things-cloud-sdk`](https://github.com/nicolai86/things-cloud-sdk); it's also a work-in-progress, relying on reverse engineering the requests on the wire
### Disclaimer
This project is not affiliated with Cultured Code. They make a fantastic product, and I hope they will provide an official way of interacting with the API one day. If you want to learn more about it, visit [culturedcode.com](https://culturedcode.com/things/).