AnkiConnect
Overview
Enable reliable interaction with Anki through the AnkiConnect local HTTP API. Use this skill to translate user requests into AnkiConnect actions, craft JSON requests, run them via curl/jq (or equivalent tools), and interpret results safely.
Preconditions and Environment
- If Anki is not running, launch Anki, then wait until the AnkiConnect server responds at
http://127.0.0.1:8765 (default). Verify readiness using curl, e.g. curl -sS http://127.0.0.1:8765 should return Anki-Connect.
Safety and Confirmation Policy (Critical)
CRITICAL — NO EXCEPTIONS
Before any destructive or modifying operation on notes or cards (adding, updating, deleting, rescheduling, suspending, unsuspending, changing deck, or changing fields/tags), request confirmation from the user. Use the AskUserQuestion tool if available; otherwise ask via chat. Only request confirmation once per logical operation, even if it requires multiple API calls (e.g., search + update + verify). Group confirmation by intent and scope (e.g., “Update 125 notes matching query X”).
Treat the following as confirmation-required by default:
- Notes:
addNote, addNotes, updateNoteFields, updateNoteTags, updateNote, updateNoteModel, deleteNotes, removeEmptyNotes, replaceTags, replaceTagsInAllNotes, clearUnusedTags.
- Cards:
setEaseFactors, setSpecificValueOfCard, suspend, unsuspend, forgetCards, relearnCards, answerCards, setDueDate, changeDeck.
- Deck or model modifications that materially change cards/notes (deck deletion, model edits). Ask even if the action is not explicitly listed above.
API Fundamentals
Request Format
Every request is JSON with:
action: string action nameversion: API version (use 6 unless user specifies otherwise)params: object of parameters (optional)
Response Format
Every response is JSON with:
result: return valueerror: null on success or a string describing the error
Always check error before using result.
Permissions
- Use
requestPermission first when interacting from a non-trusted origin; it is the only action that accepts any origin.
- Use
version to ensure compatibility; older versions may omit the error field in responses when version ≤ 4.
curl + jq Patterns
Prefer jq to build JSON and parse responses. Keep requests explicit and structured.
Minimal request template
jq -n --arg action "deckNames" --argjson version 6 '{action:$action, version:$version}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
With params
jq -n \
--arg action "findNotes" \
--argjson version 6 \
--arg query "deck:French tag:verbs" \
'{action:$action, version:$version, params:{query:$query}}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
Handling result/error
curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @- \
| jq -e 'if .error then halt_error(1) else .result end'
Batching multiple actions
Use multi to reduce round-trips and to group actions under a single confirmation when modifying data.
jq -n --argjson version 6 --arg query "deck:French" \
'{action:"multi", version:$version, params:{actions:[
{action:"findNotes", params:{query:$query}},
{action:"notesInfo", params:{notes:[]}}
]}}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
Replace the empty array with the result of the previous action when chaining; in CLI usage, split into two calls unless using a scripting language.
Core Workflow Guidance
1) Verify connectivity and version
- Call
requestPermission (safe).
- Call
version to confirm the API level and use version: 6 in requests.
2) Discover supported actions
- Use
apiReflect with scopes: ["actions"] to list supported actions.
- Use this list to map user intent to action names.
3) Resolve user request into action sequence
- Identify read-only vs destructive operations.
- For destructive/modifying operations on notes/cards, request confirmation once with the scope and count.
- Prefer
findNotes/findCards + notesInfo/cardsInfo for previews before modification.
4) Execute and validate
- Execute the call(s) in order.
- Check
error for each response.
- Report summarized results and any IDs returned.
Common Task Recipes (CLI-Oriented)
List decks
Create deck
- Action:
createDeck
- Confirmation required if the deck is being created as part of a card/note modification workflow.
Search notes / cards
- Actions:
findNotes, findCards
- Use Anki search syntax (see “Search Syntax Quick Notes” below).
Preview note data
- Action:
notesInfo (note IDs)
Add notes
- Actions:
addNote, addNotes
- Confirmation required.
- Use
canAddNotes or canAddNotesWithErrorDetail for preflight checks.
Update note fields or tags
- Actions:
updateNoteFields, updateNoteTags, or combined updateNote
- Confirmation required.
- Warning: Do not have the note open in the browser; updates may fail to apply.
Delete notes
- Action:
deleteNotes
- Confirmation required.
Suspend/unsuspend cards
- Actions:
suspend, unsuspend
- Confirmation required.
Move cards to a deck
- Action:
changeDeck
- Confirmation required.
Set due date or reschedule
- Action:
setDueDate
- Confirmation required.
Media upload/download
- Actions:
storeMediaFile, retrieveMediaFile, getMediaFilesNames, getMediaDirPath, deleteMediaFile
- Use base64 (
data), file path (path), or URL (url) for upload.
Sync
Search Syntax Quick Notes (for findNotes/findCards)
- Separate terms by spaces; terms are ANDed by default.
- Use
or, parentheses, and - for NOT logic.
- Use
deck:Name, tag:tagname, note:ModelName, card:CardName.
- Use
front:... or other field names to limit by field.
- Use
re: for regex, w: for word-boundary searches, nc: to ignore accents.
- Use
is:due, is:new, is:learn, is:review, is:suspended, is:buried to filter card states.
- Use
prop: searches for properties like interval or due date.
- Escape special characters with quotes or backslashes as needed.
Action Catalog (Use as a mapping reference)
Card Actions
getEaseFactorssetEaseFactorssetSpecificValueOfCardsuspendunsuspendsuspendedareSuspendedareDuegetIntervalsfindCardscardsToNotescardsModTimecardsInfoforgetCardsrelearnCardsanswerCardssetDueDate
Deck Actions
deckNamesdeckNamesAndIdsgetDeckscreateDeckchangeDeckdeleteDecksgetDeckConfigsaveDeckConfigsetDeckConfigIdcloneDeckConfigIdremoveDeckConfigIdgetDeckStats
Graphical Actions
guiBrowseguiSelectCardguiSelectedNotesguiAddCardsguiEditNoteguiAddNoteSetDataguiCurrentCardguiStartCardTimerguiShowQuestionguiShowAnswerguiAnswerCardguiUndoguiDeckOverviewguiDeckBrowserguiDeckReviewguiImportFileguiExitAnkiguiCheckDatabaseguiPlayAudio
Media Actions
storeMediaFileretrieveMediaFilegetMediaFilesNamesgetMediaDirPathdeleteMediaFile
Miscellaneous Actions
requestPermissionversionapiReflectsyncgetProfilesgetActiveProfileloadProfilemultiexportPackageimportPackagereloadCollection
Model Actions
modelNamesmodelNamesAndIdsfindModelsByIdfindModelsByNamemodelFieldNamesmodelFieldDescriptionsmodelFieldFontsmodelFieldsOnTemplatescreateModelmodelTemplatesmodelStylingupdateModelTemplatesupdateModelStylingfindAndReplaceInModelsmodelTemplateRenamemodelTemplateRepositionmodelTemplateAddmodelTemplateRemovemodelFieldRenamemodelFieldRepositionmodelFieldAddmodelFieldRemovemodelFieldSetFontmodelFieldSetFontSizemodelFieldSetDescription
Note Actions
addNoteaddNotescanAddNotescanAddNotesWithErrorDetailupdateNoteFieldsupdateNoteupdateNoteModelupdateNoteTagsgetNoteTagsaddTagsremoveTagsgetTagsclearUnusedTagsreplaceTagsreplaceTagsInAllNotesfindNotesnotesInfonotesModTimedeleteNotesremoveEmptyNotes
Statistic Actions
getNumCardsReviewedTodaygetNumCardsReviewedByDaygetCollectionStatsHTMLcardReviewsgetReviewsOfCardsgetLatestReviewIDinsertReviews
Notes and Pitfalls
- Keep Anki in the foreground on macOS or disable App Nap to prevent AnkiConnect from pausing.
- When updating a note, ensure it is not being viewed in the browser editor; updates may not apply.
importPackage paths are relative to the Anki collection.media folder, not the client.deleteDecks requires cardsToo: true to delete cards along with decks.
Resources
No bundled scripts or assets are required for this skill.
