Akiflow API (reverse-engineered)

Unofficial client and documentation for the Akiflow web app API, reverse-engineered from web.akiflow.com. Use with your own account only; no official API is documented by Akiflow.

You can create and update Akiflow tasks from Python, the CLI (akiflow), or an HTTP server (webhooks, Zapier, n8n).

Documentation

Full docs are in the docs/ folder:

Doc	Description
Installation	Install the package, set up .env, get a token
Usage	Python API, CLI reference, HTTP server and examples
Configuration	Environment variables and CLI options
Auth and tokens	How to get and refresh the Bearer token (login script, DevTools)
API overview	Base URLs and headers (for contributors)
Endpoints	Per-endpoint reference (tasks, calendars, user, etc.)

Quick start

pip install -e .
pip install playwright
playwright install chromium
python scripts/login_and_save_token.py   # open browser, log in → token saved to .env
akiflow task create "My first task"

From Python: from akiflow_api import create_task; create_task("Hello"). To expose an HTTP API for webhooks: pip install "akiflow-api[server]" then akiflow serve.

How we reverse-engineer the API

Because Akiflow doesn’t publish a public API, we discover endpoints by watching the traffic the web app sends when you use it.

1. Capture traffic with your account

1. Log in at web.akiflow.com in a browser where you can use DevTools.
2. Open DevTools (F12 or Cmd+Option+I) → Network tab.
3. Enable “Preserve log” so requests aren’t cleared on navigation.
4. Use the app as a normal user:
   • Open lists, tasks, calendar, settings, etc.
   • Create/edit/delete a task, change dates, add to projects, etc.
   • Do anything you want to support via the “user API” later.
5. Inspect requests:
   • Filter by Fetch/XHR to see API-style calls.
   • Note the Request URL (base URL + path), Method, Request Headers (especially Authorization or cookies), and Request/Response bodies.

2. Identify base URL and auth

• Base URL: Look at the host and path prefix of API calls (e.g. https://api.akiflow.com or https://web.akiflow.com/api/...). Record it in docs/api-overview.md.
• Auth: Check whether the app uses:
  • Cookies (session cookie for web.akiflow.com), or
  • Headers (e.g. Authorization: Bearer <token> or a custom API key).
  • For a script/client we usually need a session cookie or token we can send with each request.

3. Document each endpoint

For every relevant request, add an entry under docs/endpoints/ (or in docs/api-overview.md) with:

• Method and path
• Purpose (e.g. “list tasks”, “create task”)
• Headers required (auth + content-type)
• Request body shape (JSON)
• Response shape (and status codes)

Use the template in docs/endpoints/README.md so we keep a consistent format.

4. Implement user-facing API calls

Once endpoints are documented:

• Implement one function per “user” operation (e.g. list_tasks(), create_task(), get_calendar()).
• Use a small client in src/ (or lib/) that:
  • Uses the same base URL and auth (cookie or token) you discovered.
  • Sends the same headers and body shapes as the web app.
• Add minimal tests or examples that call these functions (using your credentials only locally).

Project layout

akiflow-api/
├── README.md
├── pyproject.toml            # Install with: pip install -e .
├── docs/
├── src/
│   ├── akiflow_api/          # Package: from akiflow_api import create_task
│   │   ├── client.py
│   │   ├── cli.py             # akiflow task create / serve
│   │   └── server.py          # Optional HTTP API
│   └── client.py             # Backward compat shim
├── scripts/
│   └── login_and_save_token.py
└── .env.example

Auth and tokens

The API uses a short-lived Bearer JWT (~30 min). Get a token with the login script or manually from DevTools. When it expires you get 401; re-run the script or re-copy. Full details: docs/auth.md.

Next steps with your account

1. Capture: Spend 15–30 minutes in the app with DevTools Network (Fetch/XHR) open; save or copy a few representative requests (URL, method, headers, body, response).
2. Document: Put base URL and auth in docs/api-overview.md, then add each endpoint to docs/endpoints/.
3. Implement: Add a thin client in src/ that uses docs/ and exposes the user API you need (tasks, calendar, etc.).
4. Credentials: Store session/token in env (e.g. .env) and never commit it; use .env.example as a template.

After you’ve captured a few real requests from your account, we can fill in docs/api-overview.md and the first endpoints, then wire up the client.