anki-connect

$27

• 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.