{"id":51548521,"url":"https://github.com/lukastk/anki-api","last_synced_at":"2026-07-09T21:01:51.272Z","repository":{"id":363642631,"uuid":"1264239547","full_name":"lukastk/anki-api","owner":"lukastk","description":"Headless REST API server wrapping an Anki collection — full feature parity (review, sync, import/export, notetypes, FSRS, image occlusion) without the Anki desktop app.","archived":false,"fork":false,"pushed_at":"2026-07-06T09:05:29.000Z","size":246,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-06T11:05:29.744Z","etag":null,"topics":["anki","fastapi","flashcards","python","rest-api","spaced-repetition"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukastk.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-06-09T17:40:17.000Z","updated_at":"2026-07-06T09:05:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lukastk/anki-api","commit_stats":null,"previous_names":["lukastk/anki-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lukastk/anki-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukastk%2Fanki-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukastk%2Fanki-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukastk%2Fanki-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukastk%2Fanki-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukastk","download_url":"https://codeload.github.com/lukastk/anki-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukastk%2Fanki-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35312540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"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":["anki","fastapi","flashcards","python","rest-api","spaced-repetition"],"created_at":"2026-07-09T21:01:50.307Z","updated_at":"2026-07-09T21:01:51.266Z","avatar_url":"https://github.com/lukastk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# anki-api\n\n[![CI](https://github.com/lukastk/anki-api/actions/workflows/ci.yml/badge.svg)](https://github.com/lukastk/anki-api/actions/workflows/ci.yml)\n\nA headless REST API server that wraps an Anki collection — create, edit, search,\nreview, sync, import/export, and manage cards over HTTP **without launching the\nAnki desktop app**. Built directly on the [`anki`](https://pypi.org/project/anki/)\npackage's `Collection` (the Rust backend via pylib/rsbridge); no Qt/GUI. Intended\nas a backend for building a custom Anki UI.\n\n## Status\n\n**Full feature parity** with the Anki feature set: 130 endpoints across 21\ndomains, backed by a rigorous test suite (211 pytest tests — unit + e2e in-process\nover the ASGI app, plus a real-`uvicorn` smoke test and a live sync test against a\nself-hosted sync server).\n\n- **API reference:** [`docs/ENDPOINTS.md`](docs/ENDPOINTS.md) (auto-generated), plus\n  interactive **`/docs`** (Swagger UI) and **`/redoc`** served by the running app.\n- **Design surface:** [`docs/api-surface-v1.md`](docs/api-surface-v1.md).\n- **Feasibility spikes the design is grounded in:** [`_dev/experiments/`](_dev/experiments/).\n\nImplemented domains: decks, deck options/presets, notes \u0026 fields, notetypes \u0026\ntemplates (incl. change-notetype), cards (flags / suspend / bury / forget /\nreposition / set-deck / restore), review (v3 scheduler, answer, set-due-date),\nsearch \u0026 browse (configurable columns, find/replace, find-duplicates), tags,\nstatistics, config \u0026 preferences, media, import/export (apkg + CSV), FSRS\ncontrols, filtered decks \u0026 custom study, undo/redo, collection maintenance (check\ndb / optimize / empty cards), **sync** (AnkiWeb or self-hosted), image occlusion\nauthoring, type-in-the-answer, TTS, and UI-chrome helpers (timespan formatting,\nmarkdown, help links).\n\n## Install \u0026 run\n\nRequires [`uv`](https://docs.astral.sh/uv/). Python is pinned to `\u003c3.13` (the\n`anki` wheel has no 3.13 build yet; `uv` selects 3.12 automatically).\n\n```sh\nuv sync\nANKI_API_COLLECTION=/path/to/collection.anki2 uv run anki-api\n# -\u003e http://127.0.0.1:8765   (interactive docs at /docs)\n```\n\nThe `.anki2` file is created if it doesn't exist. **Do not point this at a\ncollection the Anki desktop app has open** — the backend takes an exclusive lock\n(see Architecture).\n\n### Environment variables\n\n| Var | Default | Meaning |\n|---|---|---|\n| `ANKI_API_COLLECTION` | *(required)* | Path to the `.anki2` file to serve (created if absent). |\n| `ANKI_API_HOST` | `127.0.0.1` | Bind host. |\n| `ANKI_API_PORT` | `8765` | Bind port. |\n| `ANKI_API_V3_SCHEDULER` | `true` | Enable the v3 scheduler on open. |\n| `ANKI_API_LANG` | `en` | Backend locale (used by i18n-dependent helpers). |\n| `ANKI_API_SYNC_USERNAME` | *(unset)* | AnkiWeb email — if set (with the password), the server auto-logs-in on startup. |\n| `ANKI_API_SYNC_PASSWORD` | *(unset)* | AnkiWeb password (used once to obtain a token, which is then persisted). |\n| `ANKI_API_SYNC_ENDPOINT` | *(unset)* | Sync server URL; unset = AnkiWeb. |\n| `ANKI_API_AUTOSYNC_INTERVAL` | `0` | Seconds between background incremental syncs; `0` disables. |\n| `ANKI_API_SYNC_AUTH_PATH` | *(next to collection)* | Where the persisted sync token (`0600`) is stored. |\n\n### Example\n\n```sh\nBASE=http://127.0.0.1:8765/v1\n\n# create a deck and a note\ncurl -s -XPOST $BASE/decks -d '{\"name\":\"Spanish\"}' -H 'content-type: application/json'\ncurl -s -XPOST $BASE/notes -H 'content-type: application/json' -d '{\n  \"deck\":\"Spanish\",\"notetype\":\"Basic\",\n  \"fields\":{\"Front\":\"the house\",\"Back\":\"la casa\"},\"tags\":[\"nouns\"]}'\n\n# get the next due card, then answer it\ncurl -s \"$BASE/review/next?deck=Spanish\"\ncurl -s -XPOST $BASE/review/answer -H 'content-type: application/json' -d '{\n  \"card_id\":\"\u003cid\u003e\",\"rating\":\"good\",\"review_token\":\"\u003ctoken from /review/next\u003e\"}'\n```\n\n## Architecture\n\nGrounded in the feasibility experiments under [`_dev/experiments/`](_dev/experiments/):\n\n- **Single owner.** The Anki backend takes an exclusive lock on a collection\n  file, so one server process owns exactly one collection, held open for the\n  process lifetime. The desktop app and this server cannot share a file (a second\n  opener gets a clean `409`).\n- **Single writer.** All access is serialized through one lock; FastAPI sync\n  endpoints run in a threadpool, so the lock is the whole concurrency story.\n- **OpChanges envelope.** Every mutating endpoint returns Anki's `OpChanges`\n  flags (`card`, `note`, `deck`, `study_queues`, …) so a reactive UI knows which\n  views to refresh.\n- **IDs as strings.** Anki's 64-bit ids exceed JS `Number.MAX_SAFE_INTEGER`, so\n  they are serialized as strings everywhere.\n- **Errors are loud.** Backend errors map to specific HTTP statuses\n  (404/409/422/400/502); anything unrecognised surfaces as a `500` rather than\n  being silently swallowed.\n\n### Sync\n\nThe server is a sync **client**, like the desktop app or AnkiDroid. `POST\n/sync/login` (omit `endpoint` for AnkiWeb, or pass a self-hosted server URL), then\n`POST /sync` for an incremental sync. A first sync or a schema change reports\n`required: full_upload | full_download | full_sync`; the client then calls `POST\n/sync/full-upload` or `/sync/full-download` explicitly (these overwrite one side,\nso the direction is a deliberate choice). Full sync briefly closes and reopens the\ncollection under the writer lock. The collection this server owns and the\nAnkiWeb/self-hosted account converge through normal sync — so your phone and\ndesktop stay in step with changes made via the API.\n\n**Staying logged in \u0026 auto-sync.** The auth token from `/sync/login` is persisted\nto a `0600` sidecar file, so a login survives restarts. If `ANKI_API_SYNC_USERNAME`\n/ `ANKI_API_SYNC_PASSWORD` are set, the server logs in automatically on startup\nwhen no token is present (the password is only used to mint a token; it isn't\nstored). Set `ANKI_API_AUTOSYNC_INTERVAL` to have the server run an incremental\nsync on that cadence in the background. Auto-sync never performs a full sync on its\nown — if one is required it's logged and left for you to resolve via the explicit\nfull-upload/download endpoints, so there's no silent data loss.\n\n## Limitations\n\n- **TTS is OS-dependent.** Audio synthesis (`/media/tts/*`, for `{{tts:}}` cards)\n  delegates to the operating system's native speech engine — available on macOS\n  and Windows, but **not on Linux**, where the backend reports \"not implemented\n  for this OS\". On a Linux host these endpoints return a clean `400`; run the\n  server on macOS/Windows for working TTS. No per-card AV-tag extraction endpoint\n  exists yet, so a UI currently derives what to play from the rendered card HTML.\n- **Single collection per process.** By design (the exclusive lock). Serve\n  multiple collections with multiple processes on different ports.\n- **Image Occlusion** authoring is supported, but occlusion *geometry* is the\n  caller's responsibility (the API takes structured shapes; it doesn't run the\n  drawing editor).\n- **Python `\u003c3.13`** until an `anki` 3.13 wheel ships.\n\n## Development\n\n```sh\nuv run pytest                 # full suite (unit + e2e, in-process)\nuv run pytest tests/unit      # fast unit tests only\n# real over-the-wire smoke test:\nANKI_API_COLLECTION=$(mktemp -d)/c.anki2 ANKI_API_PORT=8799 uv run anki-api \u0026\nBASE=http://127.0.0.1:8799 uv run python tests/smoke.py\n```\n\nLayout: `src/anki_api/` — `app.py` (factory + lifespan), `collection_handle.py`\n(the single-owner lock), `config.py`, `errors.py`, `ids.py`, `schemas/`, and one\nmodule per domain under `routers/`. Tests mirror this under `tests/unit` and\n`tests/e2e`.\n\nThe project was built experiments-first; the durable findings from those spikes\nlive in [`_dev/experiments/EXPERIMENTS_PLAN.md`](_dev/experiments/EXPERIMENTS_PLAN.md).\n\n## License\n\n[AGPL-3.0-or-later](LICENSE). This project builds on the `anki` package, which is\nAGPL-3.0-licensed, and the AGPL's network clause applies to software served over a\nnetwork — so if you run a modified version as a network service, you must offer\nits source to users. Fine for personal/self-hosted use; a real consideration if\nyou offer it as a hosted product.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukastk%2Fanki-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukastk%2Fanki-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukastk%2Fanki-api/lists"}