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 name version: API version (use 6 unless user specifies otherwise) params: object of parameters (optional) Response Format
Every response is JSON with:
result: return value error: 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 Action: deckNames 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 Action: 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 getEaseFactors setEaseFactors setSpecificValueOfCard suspend unsuspend suspended areSuspended areDue getIntervals findCards cardsToNotes cardsModTime cardsInfo forgetCards relearnCards answerCards setDueDate Deck Actions deckNames deckNamesAndIds getDecks createDeck changeDeck deleteDecks getDeckConfig saveDeckConfig setDeckConfigId cloneDeckConfigId removeDeckConfigId getDeckStats Graphical Actions guiBrowse guiSelectCard guiSelectedNotes guiAddCards guiEditNote guiAddNoteSetData guiCurrentCard guiStartCardTimer guiShowQuestion guiShowAnswer guiAnswerCard guiUndo guiDeckOverview guiDeckBrowser guiDeckReview guiImportFile guiExitAnki guiCheckDatabase guiPlayAudio Media Actions storeMediaFile retrieveMediaFile getMediaFilesNames getMediaDirPath deleteMediaFile Miscellaneous Actions requestPermission version apiReflect sync getProfiles getActiveProfile loadProfile multi exportPackage importPackage reloadCollection Model Actions modelNames modelNamesAndIds findModelsById findModelsByName modelFieldNames modelFieldDescriptions modelFieldFonts modelFieldsOnTemplates createModel modelTemplates modelStyling updateModelTemplates updateModelStyling findAndReplaceInModels modelTemplateRename modelTemplateReposition modelTemplateAdd modelTemplateRemove modelFieldRename modelFieldReposition modelFieldAdd modelFieldRemove modelFieldSetFont modelFieldSetFontSize modelFieldSetDescription Note Actions addNote addNotes canAddNotes canAddNotesWithErrorDetail updateNoteFields updateNote updateNoteModel updateNoteTags getNoteTags addTags removeTags getTags clearUnusedTags replaceTags replaceTagsInAllNotes findNotes notesInfo notesModTime deleteNotes removeEmptyNotes Statistic Actions getNumCardsReviewedToday getNumCardsReviewedByDay getCollectionStatsHTML cardReviews getReviewsOfCards getLatestReviewID insertReviews 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.