You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
result — the return value (type depends on action)
error — null on success, error message string on failure
Always check error first — result may be null even on success (e.g., createDeck).
Error Handling
{"result": null, "error": "collection is not available"}
{"result": null, "error": "cannot create note because it is a duplicate"}
{"result": null, "error": "model was not found: NonExistentModel"}
Common errors:
Error
Cause
Connection refused
Anki not running or AnkiConnect not installed
collection is not available
Anki is open but profile not loaded
cannot create note because it is a duplicate
Note with same first field exists
model was not found
Invalid modelName
deck was not found
Deck doesn't exist (use createDeck first)
curl Examples
# Simple — no params
curl -s http://localhost:8765 -d '{"action":"version","version":6}'# With params
curl -s http://localhost:8765 -d '{ "action":"deckNames", "version":6}'# Pretty-print with python
curl -s http://localhost:8765 -d '{"action":"deckNames","version":6}'| python3 -m json.tool
A knowledge unit with fields (Front, Back, etc.) — one note can generate multiple cards
Card
A reviewable item generated from a note — has scheduling state (due date, interval, etc.)
Deck
A collection of cards — each card belongs to exactly one deck
Model (Note Type)
Defines fields and card templates — e.g., "Basic" has Front/Back fields
Tag
Metadata label on notes (not cards) — space-separated in import files
Important: Notes and cards are different things. A "Basic" note creates 1 card.
A "Basic (and reversed card)" note creates 2 cards (forward + reverse).
API operations target either notes (content) or cards (scheduling).
{"result": null, "error": "cannot create note because it is a duplicate"}
This makes addNote idempotent — safe to call repeatedly with the same data.
TSV File Import (Failover Mode)
When AnkiConnect is unavailable, export cards as tab-separated values (.tsv) and import
manually via Anki Desktop.
TSV Format
# Lines starting with # are ignored
# Fields separated by TAB: Front, Back, Tags (space-separated)
Wie viele Kantone hat die Schweiz? 26 Kantone geography facts ch01
Was ist die Bundesstadt? Bern<br>(keine offizielle Hauptstadt) geography facts ch01
Fields are tab-separated (not comma, not semicolon)
HTML is supported in field values (<br>, <b>, etc.)
Tags are space-separated within the tags column
Lines starting with # are comments (ignored by Anki)
Import Steps
File → Import... in Anki Desktop
Select the .tsv file
Configure:
Field separator: Tab
Allow HTML in fields: Yes
Existing notes: Update (default) or Ignore
Deck: select target deck
Field mapping: Field 1 → Front, Field 2 → Back, Field 3 → Tags
"When importing text files, Anki uses the first field to determine if a note is unique."
The first field (Front) acts as a primary key — analogous to a database primary key.
The composite identity is (note_type, first_field). If two notes share the same note type
and first field value, Anki treats them as the same note. All deduplication logic — both
in file import and AnkiConnect API — keys off this pair.
Default Behavior: Update in Place
"By default, if the file you are importing has a first field that matches one of the
existing notes in your collection and that existing note is the same type as the type
you're importing, the existing note's other fields will be updated based on content of
the imported file."
This means re-importing a file is safe — it updates existing cards rather than creating duplicates.
Three Duplicate Handling Modes
"A drop-down box in the import screen allows you to change this behaviour, to either
ignore duplicates completely, or import them as new notes instead of updating existing ones."
Mode
Behavior
Use when
Update existing notes (default)
Matched notes get non-key fields overwritten
You improved card content
Ignore duplicates
Matched notes skipped entirely
Safe re-import, no overwrites
Import as new notes
No dedup, creates duplicates
Almost never — avoid this
Scheduling Is Preserved
"If you have updating turned on and older versions of the notes you're importing are
already in your collection, they will be updated in place (in their current decks)
rather than being moved to the deck you have set in the import dialog. If notes are
updated in place, the existing scheduling information on all their cards will be preserved."
Key takeaway: re-importing does not reset your review progress.
Match Scope
"The match scope setting controls how duplicates are identified. When note type is
selected, Anki will identify a duplicate if another note with the same note type has the
same first field. When set to note type and deck, a duplicate will only be flagged if
the existing note also happens to be in the deck you are importing into."
Match Scope
Dedup scope
Note type (default)
Collection-wide — safest
Note type and deck
Only within target deck — can create duplicates across decks
One Card = One Deck (No Cross-Deck Superposition)
Each card belongs to exactly one deck at any given time. A card cannot exist in
multiple decks simultaneously — there is no "superposition" where the same card shares
scheduling state across decks.
Cards are moved (not copied) to filtered decks, and each card retains a link to
its "home deck" — the single deck it belongs to.
Consequence: if you import the same .tsv file into deck A and then into deck B:
Match scope = note type (default): duplicate detected → card stays in deck A,
updated in place. Deck B gets nothing. Scheduling in A is preserved.
Match scope = note type and deck: not flagged as duplicate → creates a second
independent note in deck B with separate, independent scheduling. These are now two
unrelated cards that happen to look the same — not a shared card.
There is no mechanism to have one card appear in two decks with shared review state.
If you want a card in a different deck, move it (changeDeck via AnkiConnect) —
this transfers it fully, including scheduling history.
Summary for Programmers
It is safe to:
Push the same batch multiple times via AnkiConnect (allowDuplicate: false)
Import the same .tsv file multiple times (default "Update" mode)
Import overlapping card sets from different files
Anki guarantees:
Primary key = (note_type, first_field) — this pair is the identity
One card, one deck — no cross-deck scheduling superposition
fromdatetimeimportdatetimecard=cards_info[0]
ifcard["type"] ==2: # REVIEW card# 'due' is relative days — compare against collection creation dateprint(f"Review in {card['interval']} days")
elifcard["type"] ==1: # LEARNING card# 'due' is Unix timestampdue_time=datetime.fromtimestamp(card["due"])
print(f"Due at {due_time}")
elifcard["type"] ==0: # NEW card# 'due' is position in new card queueprint(f"Queue position: {card['due']}")
Example: Full Deck Snapshot
This Python snippet dumps the full scheduling state of a deck:
[REVIEW ] interval= 5d reps=1 lapses=0 Wie viele Mitglieder hat der Bundesrat?
[LEARNING ] interval= 0d reps=4 lapses=0 Was ist die Bundesversammlung?
[REVIEW ] interval= 3d reps=1 lapses=0 du-Form von «dürfen»: «Du ___ in der Sc
[REVIEW ] interval= 1d reps=2 lapses=0 sein/ihr? — «Die Schweiz hat ___ Bundess
Collection-Level Statistics
# Number of cards reviewed today
curl -s http://localhost:8765 -d '{ "action": "getNumCardsReviewedToday", "version": 6}'# Review counts by day (last 30 days)
curl -s http://localhost:8765 -d '{ "action": "getNumCardsReviewedByDay", "version": 6}'# → {"result": [["2026-03-08", 4], ["2026-03-07", 12], ...]}# Collection stats HTML (same as Anki's Stats screen)
curl -s http://localhost:8765 -d '{ "action": "getCollectionStatsHTML", "version": 6, "params": {"wholeCollection": true}}'
Useful Queries for Agents
# Cards due today across all decks
curl -s http://localhost:8765 -d '{"action":"findCards","version":6,"params":{"query":"is:due"}}'# New cards not yet seen
curl -s http://localhost:8765 -d '{"action":"findCards","version":6,"params":{"query":"deck:MyDeck is:new"}}'# Cards with lapses (forgotten at least once)
curl -s http://localhost:8765 -d '{"action":"findCards","version":6,"params":{"query":"deck:MyDeck prop:lapses>0"}}'# Cards with low ease (struggling cards)
curl -s http://localhost:8765 -d '{"action":"findCards","version":6,"params":{"query":"deck:MyDeck prop:ease<2"}}'# Cards reviewed in last 7 days
curl -s http://localhost:8765 -d '{"action":"findCards","version":6,"params":{"query":"deck:MyDeck rated:7"}}'
07 — Moving, Splitting, and Merging Decks (Scheduling Preservation Proof)
TL;DR
Yes — you can freely move cards between decks, split decks, and merge decks without
losing any scheduling data (intervals, due dates, ease factors, review history, lapse
counts). Scheduling is a property of the card, not the deck. Decks are organizational
containers only.
Official Evidence
No single Anki doc contains an explicit statement "scheduling is stored on the card, not
the deck." Instead, this is established by converging evidence from multiple official sources.
Evidence 1: "Change Deck" Has No Scheduling Side-Effects
"If you have updating turned on and older versions of the notes you're importing are
already in your collection, they will be updated in place (in their current decks)
rather than being moved to the deck you have set in the import dialog. If notes are
updated in place, the existing scheduling information on all their cards will be preserved."
This is the most explicit official statement about scheduling preservation.
"Deck options are not retroactive. For example, if you change an option that controls
the delay after failing a card, cards that you failed before changing this option will
still have the old delay, not the new one."
"When Anki shows a card, it will check which subdeck the card is in, and use the options
for that deck."
This confirms: existing interval/ease/due are baked into the card record. Deck options
govern future scheduling computations, not past state. Moving a card to a new deck changes
which options apply going forward but does not touch existing scheduling data.
Evidence 4: Ease and Interval Are Card-Level Fields
"When a card is moved to a filtered deck, it retains a link to the deck from which it
came. That previous deck is said to be the card's 'home deck'."
"By default, Anki will return cards to their home decks with altered scheduling,
based on your performance in the filtered deck."
Filtered decks are the one case where Anki explicitly does modify scheduling on
deck transition — and the manual documents this explicitly with a toggle to disable it.
Regular deck moves (Change Deck, changeDeck API) have no such documentation because
they don't modify scheduling.
Evidence 6: AnkiConnect changeDeck — No Scheduling Parameters
