anki-connect（安基连接）

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.