From fd4a32f49d15767cddcb6ddd2a465cb4f277fcfd Mon Sep 17 00:00:00 2001 From: Alex Yatskov Date: Sun, 24 May 2020 17:23:37 -0700 Subject: [PATCH] Update documentation format --- README.md | 1845 +------------------------------------- actions/cards.md | 247 +++++ actions/decks.md | 331 +++++++ actions/graphical.md | 274 ++++++ actions/media.md | 99 ++ actions/miscellaneous.md | 170 ++++ actions/models.md | 311 +++++++ actions/notes.md | 325 +++++++ actions/statistics.md | 44 + 9 files changed, 1813 insertions(+), 1833 deletions(-) create mode 100644 actions/cards.md create mode 100644 actions/decks.md create mode 100644 actions/graphical.md create mode 100644 actions/media.md create mode 100644 actions/miscellaneous.md create mode 100644 actions/models.md create mode 100644 actions/notes.md create mode 100644 actions/statistics.md diff --git a/README.md b/README.md index d0de165..7e41092 100644 --- a/README.md +++ b/README.md @@ -5,23 +5,6 @@ The AnkiConnect plugin enables external applications such as [Yomichan](https:// the user's card deck, automatically create new vocabulary and Kanji flash cards, and more. AnkiConnect is compatible with the latest stable (2.1.x) releases of Anki; older versions (2.0.x and below) are no longer supported. -## Table of Contents - -* [Installation](#installation) - * [Notes for Windows Users](#notes-for-windows-users) - * [Notes for Mac OS X Users](#notes-for-mac-os-x-users) -* [Application Interface for Developers](#application-interface-for-developers) - * [Sample Invocation](#sample-invocation) - * [Supported Actions](#supported-actions) - * [Miscellaneous](#miscellaneous) - * [Statistics](#statistics) - * [Decks](#decks) - * [Models](#models) - * [Notes](#notes) - * [Cards](#cards) - * [Media](#media) - * [Graphical](#graphical) - ## Installation The installation process is similar to that of other Anki plugins and can be accomplished in three steps: @@ -169,1819 +152,15 @@ console.log(`got list of decks: ${result}`); ### Supported Actions -Below is a comprehensive list of currently supported actions. Note that deprecated APIs will continue to function -despite not being listed on this page as long as your request is labeled with a version number corresponding to when the -API was available for use. - -This page currently documents **version 6** of the API. Make sure to include this version number in your requests to -guarantee that your application continues to function properly in the future. - -#### Miscellaneous - -* **version** - - Gets the version of the API exposed by this plugin. Currently versions `1` through `6` are defined. - - This should be the first call you make to make sure that your application and AnkiConnect are able to communicate - properly with each other. New versions of AnkiConnect are backwards compatible; as long as you are using actions - which are available in the reported AnkiConnect version or earlier, everything should work fine. - - *Sample request*: - ```json - { - "action": "version", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": 6, - "error": null - } - ``` - -* **sync** - - Synchronizes the local Anki collections with AnkiWeb. - - *Sample request*: - ```json - { - "action": "sync", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **getProfiles** - - Retrieve the list of profiles. - - *Sample request*: - ```json - { - "action": "getProfiles", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": ["User 1"], - "error": null - } - ``` - -* **loadProfile** - - Selects the profile specified in request. - - *Sample request*: - ```json - { - "action": "loadProfile", - "params": { - "name": "user1" - }, - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **multi** - - Performs multiple actions in one request, returning an array with the response of each action (in the given order). - - *Sample request*: - ```json - { - "action": "multi", - "version": 6, - "params": { - "actions": [ - {"action": "deckNames"}, - { - "action": "browse", - "params": {"query": "deck:current"} - } - ] - } - } - ``` - - *Sample result*: - ```json - { - "result": [ - {"result": "Default", "error": null}, - {"result": [1494723142483, 1494703460437, 1494703479525], "error": null} - ], - "error": null - } - ``` - -* **exportPackage** - - Exports a given deck in `.apkg` format. Returns `true` if successful or `false` otherwise. The optional property - `includeSched` (default is `false`) can be specified to include the cards' scheduling data. - - *Sample request*: - ```json - { - "action": "exportPackage", - "version": 6, - "params": { - "deck": "Default", - "path": "/data/Deck.apkg", - "includeSched": true - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **importPackage** - - Imports a file in `.apkg` format into the collection. Returns `true` if successful or `false` otherwise. - Note that the file path is relative to Anki's collection.media folder, not to the client. - - *Sample request*: - ```json - { - "action": "importPackage", - "version": 6, - "params": { - "path": "/data/Deck.apkg", - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -#### Statistics - -* **getNumCardsReviewedToday** - - Gets the count of cards that have been reviewed in the current day (with day start time as configured by user in anki) - - *Sample request*: - ```json - { - "action": "getNumCardsReviewedToday", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": 0, - "error": null - } - ``` - -* **getCollectionStatsHTML** - - Gets the collection statistics report - - *Sample request*: - ```json - { - "action": "getCollectionStatsHTML", - "version": 6, - "params": { - "wholeCollection": true - } - } - ``` - - *Sample result*: - ```json - { - "error": null, - "result": "
lots of HTML here
", - } - ``` - -#### Decks - -* **deckNames** - - Gets the complete list of deck names for the current user. - - *Sample request*: - ```json - { - "action": "deckNames", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": ["Default"], - "error": null - } - ``` - -* **deckNamesAndIds** - - Gets the complete list of deck names and their respective IDs for the current user. - - *Sample request*: - ```json - { - "action": "deckNamesAndIds", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": {"Default": 1}, - "error": null - } - ``` - -* **getDecks** - - Accepts an array of card IDs and returns an object with each deck name as a key, and its value an array of the given - cards which belong to it. - - *Sample request*: - ```json - { - "action": "getDecks", - "version": 6, - "params": { - "cards": [1502298036657, 1502298033753, 1502032366472] - } - } - ``` - - *Sample result*: - ```json - { - "result": { - "Default": [1502032366472], - "Japanese::JLPT N3": [1502298036657, 1502298033753] - }, - "error": null - } - ``` - -* **createDeck** - - Create a new empty deck. Will not overwrite a deck that exists with the same name. - - *Sample request*: - ```json - { - "action": "createDeck", - "version": 6, - "params": { - "deck": "Japanese::Tokyo" - } - } - ``` - - *Sample result*: - ```json - { - "result": 1519323742721, - "error": null - } - ``` -* **changeDeck** - - Moves cards with the given IDs to a different deck, creating the deck if it doesn't exist yet. - - *Sample request*: - ```json - { - "action": "changeDeck", - "version": 6, - "params": { - "cards": [1502098034045, 1502098034048, 1502298033753], - "deck": "Japanese::JLPT N3" - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **deleteDecks** - - Deletes decks with the given names. If `cardsToo` is `true` (defaults to `false` if unspecified), the cards within - the deleted decks will also be deleted; otherwise they will be moved to the default deck. - - *Sample request*: - ```json - { - "action": "deleteDecks", - "version": 6, - "params": { - "decks": ["Japanese::JLPT N5", "Easy Spanish"], - "cardsToo": true - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **getDeckConfig** - - Gets the configuration group object for the given deck. - - *Sample request*: - ```json - { - "action": "getDeckConfig", - "version": 6, - "params": { - "deck": "Default" - } - } - ``` - - *Sample result*: - ```json - { - "result": { - "lapse": { - "leechFails": 8, - "delays": [10], - "minInt": 1, - "leechAction": 0, - "mult": 0 - }, - "dyn": false, - "autoplay": true, - "mod": 1502970872, - "id": 1, - "maxTaken": 60, - "new": { - "bury": true, - "order": 1, - "initialFactor": 2500, - "perDay": 20, - "delays": [1, 10], - "separate": true, - "ints": [1, 4, 7] - }, - "name": "Default", - "rev": { - "bury": true, - "ivlFct": 1, - "ease4": 1.3, - "maxIvl": 36500, - "perDay": 100, - "minSpace": 1, - "fuzz": 0.05 - }, - "timer": 0, - "replayq": true, - "usn": -1 - }, - "error": null - } - ``` - -* **saveDeckConfig** - - Saves the given configuration group, returning `true` on success or `false` if the ID of the configuration group is - invalid (such as when it does not exist). - - *Sample request*: - ```json - { - "action": "saveDeckConfig", - "version": 6, - "params": { - "config": { - "lapse": { - "leechFails": 8, - "delays": [10], - "minInt": 1, - "leechAction": 0, - "mult": 0 - }, - "dyn": false, - "autoplay": true, - "mod": 1502970872, - "id": 1, - "maxTaken": 60, - "new": { - "bury": true, - "order": 1, - "initialFactor": 2500, - "perDay": 20, - "delays": [1, 10], - "separate": true, - "ints": [1, 4, 7] - }, - "name": "Default", - "rev": { - "bury": true, - "ivlFct": 1, - "ease4": 1.3, - "maxIvl": 36500, - "perDay": 100, - "minSpace": 1, - "fuzz": 0.05 - }, - "timer": 0, - "replayq": true, - "usn": -1 - } - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **setDeckConfigId** - - Changes the configuration group for the given decks to the one with the given ID. Returns `true` on success or - `false` if the given configuration group or any of the given decks do not exist. - - *Sample request*: - ```json - { - "action": "setDeckConfigId", - "version": 6, - "params": { - "decks": ["Default"], - "configId": 1 - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **cloneDeckConfigId** - - Creates a new configuration group with the given name, cloning from the group with the given ID, or from the default - group if this is unspecified. Returns the ID of the new configuration group, or `false` if the specified group to - clone from does not exist. - - *Sample request*: - ```json - { - "action": "cloneDeckConfigId", - "version": 6, - "params": { - "name": "Copy of Default", - "cloneFrom": 1 - } - } - ``` - - *Sample result*: - ```json - { - "result": 1502972374573, - "error": null - } - ``` - -* **removeDeckConfigId** - - Removes the configuration group with the given ID, returning `true` if successful, or `false` if attempting to - remove either the default configuration group (ID = 1) or a configuration group that does not exist. - - *Sample request*: - ```json - { - "action": "removeDeckConfigId", - "version": 6, - "params": { - "configId": 1502972374573 - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -#### Models - -* **modelNames** - - Gets the complete list of model names for the current user. - - *Sample request*: - ```json - { - "action": "modelNames", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": ["Basic", "Basic (and reversed card)"], - "error": null - } - ``` - -* **modelNamesAndIds** - - Gets the complete list of model names and their corresponding IDs for the current user. - - *Sample request*: - ```json - { - "action": "modelNamesAndIds", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": { - "Basic": 1483883011648, - "Basic (and reversed card)": 1483883011644, - "Basic (optional reversed card)": 1483883011631, - "Cloze": 1483883011630 - }, - "error": null - } - ``` - -* **modelFieldNames** - - Gets the complete list of field names for the provided model name. - - *Sample request*: - ```json - { - "action": "modelFieldNames", - "version": 6, - "params": { - "modelName": "Basic" - } - } - ``` - - *Sample result*: - ```json - { - "result": ["Front", "Back"], - "error": null - } - ``` - -* **modelFieldsOnTemplates** - - Returns an object indicating the fields on the question and answer side of each card template for the given model - name. The question side is given first in each array. - - *Sample request*: - ```json - { - "action": "modelFieldsOnTemplates", - "version": 6, - "params": { - "modelName": "Basic (and reversed card)" - } - } - ``` - - *Sample result*: - ```json - { - "result": { - "Card 1": [["Front"], ["Back"]], - "Card 2": [["Back"], ["Front"]] - }, - "error": null - } - ``` - - -* **createModel** - - Creates a new model to be used in Anki. User must provide the `modelName`, `inOrderFields` and `cardTemplates` to be - used in the model. Optionally the `Name` field can be provided for each entry of `cardTemplates`. By default the - card names will be `Card 1`, `Card 2`, and so on. - - *Sample request* - ```json - { - "action": "createModel", - "version": 6, - "params": { - "modelName": "newModelName", - "inOrderFields": ["Field1", "Field2", "Field3"], - "css": "Optional CSS with default to builtin css", - "cardTemplates": [ - { - "Name": "My Card 1", - "Front": "Front html {{Field1}}", - "Back": "Back html {{Field2}}" - } - ] - } - } - ``` - - *Sample result* - ```json - { - "result":{ - "sortf":0, - "did":1, - "latexPre":"\\documentclass[12pt]{article}\n\\special{papersize=3in,5in}\n\\usepackage[utf8]{inputenc}\n\\usepackage{amssymb,amsmath}\n\\pagestyle{empty}\n\\setlength{\\parindent}{0in}\n\\begin{document}\n", - "latexPost":"\\end{document}", - "mod":1551462107, - "usn":-1, - "vers":[ - - ], - "type":0, - "css":".card {\n font-family: arial;\n font-size: 20px;\n text-align: center;\n color: black;\n background-color: white;\n}\n", - "name":"TestApiModel", - "flds":[ - { - "name":"Field1", - "ord":0, - "sticky":false, - "rtl":false, - "font":"Arial", - "size":20, - "media":[ - - ] - }, - { - "name":"Field2", - "ord":1, - "sticky":false, - "rtl":false, - "font":"Arial", - "size":20, - "media":[ - - ] - } - ], - "tmpls":[ - { - "name":"My Card 1", - "ord":0, - "qfmt":"", - "afmt":"This is the back of the card {{Field2}}", - "did":null, - "bqfmt":"", - "bafmt":"" - } - ], - "tags":[ - - ], - "id":"1551462107104", - "req":[ - [ - 0, - "none", - [ - - ] - ] - ] - }, - "error":null - } - ``` - - -* **modelTemplates** - - Returns an object indicating the template content for each card connected to the provided model by name. - - *Sample request*: - ```json - { - "action": "modelTemplates", - "version": 6, - "params": { - "modelName": "Basic (and reversed card)" - } - } - ``` - - *Sample result* - ```json - { - "result": { - "Card 1": { - "Front": "{{Front}}", - "Back": "{{FrontSide}}\n\n
\n\n{{Back}}" - }, - "Card 2": { - "Front": "{{Back}}", - "Back": "{{FrontSide}}\n\n
\n\n{{Front}}" - } - }, - "error": null - } - ``` - - -* **modelStyling** - - Gets the CSS styling for the provided model by name. - - *Sample request*: - ```json - { - "action": "modelStyling", - "version": 6, - "params": { - "modelName": "Basic (and reversed card)" - } - } - ``` - - *Sample result* - ```json - { - "result": { - "css": ".card {\n font-family: arial;\n font-size: 20px;\n text-align: center;\n color: black;\n background-color: white;\n}\n" - }, - "error": null - } - ``` - - -* **updateModelTemplates** - - Modify the templates of an existing model by name. Only specifies cards and specified sides will be modified. - If an existing card or side is not included in the request, it will be left unchanged. - - *Sample request*: - ```json - { - "action": "updateModelTemplates", - "version": 6, - "params": { - "model": { - "name": "Custom", - "templates": { - "Card 1": { - "Front": "{{Question}}?", - "Back": "{{Answer}}!" - } - } - } - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - - -* **updateModelStyling** - - Modify the CSS styling of an existing model by name. - - *Sample request*: - ```json - { - "action": "updateModelStyling", - "version": 6, - "params": { - "model": { - "name": "Custom", - "css": "p { color: blue; }" - } - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -#### Notes - -* **addNote** - - Creates a note using the given deck and model, with the provided field values and tags. Returns the identifier of - the created note created on success, and `null` on failure. - - AnkiConnect can download audio files and embed them in newly created notes. The corresponding `audio` note member is - optional and can be omitted. If you choose to include it, it should contain a single object or an array of objects - with mandatory `url` and `filename` fields. The `skipHash` field can be optionally provided to skip the inclusion of - downloaded files with an MD5 hash that matches the provided value. This is useful for avoiding the saving of error - pages and stub files. The `fields` member is a list of fields that should play audio when the card is displayed in - Anki. The `allowDuplicate` member inside `options` group can be set to true to enable adding duplicate cards. - Normally duplicate cards can not be added and trigger exception. The `duplicateScope` member inside `options` can be - used to specify the scope for which duplicates are checked. A value of `"deck"` will only check for duplicates in the - target deck; any other value will check the entire collection. - - *Sample request*: - ```json - { - "action": "addNote", - "version": 6, - "params": { - "note": { - "deckName": "Default", - "modelName": "Basic", - "fields": { - "Front": "front content", - "Back": "back content" - }, - "options": { - "allowDuplicate": false, - "duplicateScope": "deck" - }, - "tags": [ - "yomichan" - ], - "audio": [{ - "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ", - "filename": "yomichan_ねこ_猫.mp3", - "skipHash": "7e2c2f954ef6051373ba916f000168dc", - "fields": [ - "Front" - ] - }] - } - } - } - ``` - - *Sample result*: - ```json - { - "result": 1496198395707, - "error": null - } - ``` - -* **addNotes** - - Creates multiple notes using the given deck and model, with the provided field values and tags. Returns an array of - identifiers of the created notes (notes that could not be created will have a `null` identifier). Please see the - documentation for `addNote` for an explanation of objects in the `notes` array. - - *Sample request*: - ```json - { - "action": "addNotes", - "version": 6, - "params": { - "notes": [ - { - "deckName": "Default", - "modelName": "Basic", - "fields": { - "Front": "front content", - "Back": "back content" - }, - "tags": [ - "yomichan" - ], - "audio": [{ - "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ", - "filename": "yomichan_ねこ_猫.mp3", - "skipHash": "7e2c2f954ef6051373ba916f000168dc", - "fields": [ - "Front" - ] - }] - } - ] - } - } - ``` - - *Sample result*: - ```json - { - "result": [1496198395707, null], - "error": null - } - ``` - -* **canAddNotes** - - Accepts an array of objects which define parameters for candidate notes (see `addNote`) and returns an array of - booleans indicating whether or not the parameters at the corresponding index could be used to create a new note. - - *Sample request*: - ```json - { - "action": "canAddNotes", - "version": 6, - "params": { - "notes": [ - { - "deckName": "Default", - "modelName": "Basic", - "fields": { - "Front": "front content", - "Back": "back content" - }, - "tags": [ - "yomichan" - ] - } - ] - } - } - ``` - - *Sample result*: - ```json - { - "result": [true], - "error": null - } - ``` - -* **updateNoteFields** - - Modify the fields of an exist note. You can also include audio files which will be added to the note with an - optional `audio` property. Please see the documentation for `addNote` for an explanation of objects in the `audio` array. - - *Sample request*: - ```json - { - "action": "updateNoteFields", - "version": 6, - "params": { - "note": { - "id": 1514547547030, - "fields": { - "Front": "new front content", - "Back": "new back content" - }, - "audio": [{ - "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ", - "filename": "yomichan_ねこ_猫.mp3", - "skipHash": "7e2c2f954ef6051373ba916f000168dc", - "fields": [ - "Front" - ] - }] - } - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **addTags** - - Adds tags to notes by note ID. - - *Sample request*: - ```json - { - "action": "addTags", - "version": 6, - "params": { - "notes": [1483959289817, 1483959291695], - "tags": "european-languages" - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **removeTags** - - Remove tags from notes by note ID. - - *Sample request*: - ```json - { - "action": "removeTags", - "version": 6, - "params": { - "notes": [1483959289817, 1483959291695], - "tags": "european-languages" - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **getTags** - - Gets the complete list of tags for the current user. - - *Sample request*: - ```json - { - "action": "getTags", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": ["european-languages", "idioms"], - "error": null - } - ``` - -* **findNotes** - - Returns an array of note IDs for a given query. Same query syntax as `guiBrowse`. - - *Sample request*: - ```json - { - "action": "findNotes", - "version": 6, - "params": { - "query": "deck:current" - } - } - ``` - - *Sample result*: - ```json - { - "result": [1483959289817, 1483959291695], - "error": null - } - ``` - -* **notesInfo** - - Returns a list of objects containing for each note ID the note fields, tags, note type and the cards belonging to - the note. - - *Sample request*: - ```json - { - "action": "notesInfo", - "version": 6, - "params": { - "notes": [1502298033753] - } - } - ``` - - *Sample result*: - ```json - { - "result": [ - { - "noteId":1502298033753, - "modelName": "Basic", - "tags":["tag","another_tag"], - "fields": { - "Front": {"value": "front content", "order": 0}, - "Back": {"value": "back content", "order": 1} - } - } - ], - "error": null - } - ``` - - -* **deleteNotes** - - Deletes notes with the given ids. If a note has several cards associated with it, all associated cards will be deleted. - - *Sample request*: - ```json - { - "action": "deleteNotes", - "version": 6, - "params": { - "notes": [1502298033753] - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - - -#### Cards - -* **suspend** - - Suspend cards by card ID; returns `true` if successful (at least one card wasn't already suspended) or `false` - otherwise. - - *Sample request*: - ```json - { - "action": "suspend", - "version": 6, - "params": { - "cards": [1483959291685, 1483959293217] - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **unsuspend** - - Unsuspend cards by card ID; returns `true` if successful (at least one card was previously suspended) or `false` - otherwise. - - *Sample request*: - ```json - { - "action": "unsuspend", - "version": 6, - "params": { - "cards": [1483959291685, 1483959293217] - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **areSuspended** - - Returns an array indicating whether each of the given cards is suspended (in the same order). - - *Sample request*: - ```json - { - "action": "areSuspended", - "version": 6, - "params": { - "cards": [1483959291685, 1483959293217] - } - } - ``` - - *Sample result*: - ```json - { - "result": [false, true], - "error": null - } - ``` - -* **areDue** - - Returns an array indicating whether each of the given cards is due (in the same order). *Note*: cards in the - learning queue with a large interval (over 20 minutes) are treated as not due until the time of their interval has - passed, to match the way Anki treats them when reviewing. - - *Sample request*: - ```json - { - "action": "areDue", - "version": 6, - "params": { - "cards": [1483959291685, 1483959293217] - } - } - ``` - - *Sample result*: - ```json - { - "result": [false, true], - "error": null - } - ``` - -* **getIntervals** - - Returns an array of the most recent intervals for each given card ID, or a 2-dimensional array of all the intervals - for each given card ID when `complete` is `true`. Negative intervals are in seconds and positive intervals in days. - - *Sample request 1*: - ```json - { - "action": "getIntervals", - "version": 6, - "params": { - "cards": [1502298033753, 1502298036657] - } - } - ``` - - *Sample result 1*: - ```json - { - "result": [-14400, 3], - "error": null - } - ``` - - *Sample request 2*: - ```json - { - "action": "getIntervals", - "version": 6, - "params": { - "cards": [1502298033753, 1502298036657], - "complete": true - } - } - ``` - - *Sample result 2*: - ```json - { - "result": [ - [-120, -180, -240, -300, -360, -14400], - [-120, -180, -240, -300, -360, -14400, 1, 3] - ], - "error": null - } - ``` - -* **findCards** - - Returns an array of card IDs for a given query. Functionally identical to `guiBrowse` but doesn't use the GUI for - better performance. - - *Sample request*: - ```json - { - "action": "findCards", - "version": 6, - "params": { - "query": "deck:current" - } - } - ``` - - *Sample result*: - ```json - { - "result": [1494723142483, 1494703460437, 1494703479525], - "error": null - } - ``` - -* **cardsToNotes** - - Returns an unordered array of note IDs for the given card IDs. For cards with the same note, the ID is only given - once in the array. - - *Sample request*: - ```json - { - "action": "cardsToNotes", - "version": 6, - "params": { - "cards": [1502098034045, 1502098034048, 1502298033753] - } - } - ``` - - *Sample result*: - ```json - { - "result": [1502098029797, 1502298025183], - "error": null - } - ``` - -* **cardsInfo** - - Returns a list of objects containing for each card ID the card fields, front and back sides including CSS, note - type, the note that the card belongs to, and deck name, as well as ease and interval. - - *Sample request*: - ```json - { - "action": "cardsInfo", - "version": 6, - "params": { - "cards": [1498938915662, 1502098034048] - } - } - ``` - - *Sample result*: - ```json - { - "result": [ - { - "answer": "back content", - "question": "front content", - "deckName": "Default", - "modelName": "Basic", - "fieldOrder": 1, - "fields": { - "Front": {"value": "front content", "order": 0}, - "Back": {"value": "back content", "order": 1} - }, - "css":"p {font-family:Arial;}", - "cardId": 1498938915662, - "interval": 16, - "note":1502298033753 - }, - { - "answer": "back content", - "question": "front content", - "deckName": "Default", - "modelName": "Basic", - "fieldOrder": 0, - "fields": { - "Front": {"value": "front content", "order": 0}, - "Back": {"value": "back content", "order": 1} - }, - "css":"p {font-family:Arial;}", - "cardId": 1502098034048, - "interval": 23, - "note":1502298033753 - } - ], - "error": null - } - ``` - -#### Media - -* **storeMediaFile** - - Stores a file with the specified base64-encoded contents inside the media folder. alternatively you can specify a - url from where the file shell be downloaded. If both field `data` and `url` are provided, the `data` field will be - used. To prevent Anki from removing files not used by any cards (e.g. for configuration files), prefix the filename - with an underscore. These files are still synchronized to AnkiWeb. - - *Sample request*: - ```json - { - "action": "storeMediaFile", - "version": 6, - "params": { - "filename": "_hello.txt", - "data": "SGVsbG8sIHdvcmxkIQ==" - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - - *Content of `_hello.txt`*: - ``` - Hello world! - ``` - - *Sample request*: - ```json - { - "action": "storeMediaFile", - "version": 6, - "params": { - "filename": "_hello.txt", - "url": "https://url.to.file" - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **retrieveMediaFile** - - Retrieves the base64-encoded contents of the specified file, returning `false` if the file does not exist. - - *Sample request*: - ```json - { - "action": "retrieveMediaFile", - "version": 6, - "params": { - "filename": "_hello.txt" - } - } - ``` - - *Sample result*: - ```json - { - "result": "SGVsbG8sIHdvcmxkIQ==", - "error": null - } - ``` - -* **deleteMediaFile** - - Deletes the specified file inside the media folder. - - *Sample request*: - ```json - { - "action": "deleteMediaFile", - "version": 6, - "params": { - "filename": "_hello.txt" - } - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -#### Graphical - -* **guiBrowse** - - Invokes the *Card Browser* dialog and searches for a given query. Returns an array of identifiers of the cards that - were found. - - *Sample request*: - ```json - { - "action": "guiBrowse", - "version": 6, - "params": { - "query": "deck:current" - } - } - ``` - - *Sample result*: - ```json - { - "result": [1494723142483, 1494703460437, 1494703479525], - "error": null - } - ``` - -* **guiAddCards** - - Invokes the *Add Cards* dialog, presets the note using the given deck and model, with the provided field values and tags. - Invoking it multiple times closes the old window and _reopen the window_ with the new provided values. - - The `closeAfterAdding` member inside `options` group can be set to true to create a dialog that closes upon adding the note. - Invoking the action mutliple times with this option will create _multiple windows_. - - The result is the ID of the note which would be added, if the user chose to confirm the *Add Cards* dialogue. - - *Sample request*: - ```json - { - "action": "guiAddCards", - "version": 6, - "params": { - "note": { - "deckName": "Default", - "modelName": "Cloze", - "fields": { - "Text": "The capital of Romania is {{c1::Bucharest}}", - "Extra": "Romania is a country in Europe" - }, - "options": { - "closeAfterAdding": true - }, - "tags": [ - "countries" - ] - } - } - } - ``` - - *Sample result*: - ```json - { - "result": 1496198395707, - "error": null - } - ``` - -* **guiCurrentCard** - - Returns information about the current card or `null` if not in review mode. - - *Sample request*: - ```json - { - "action": "guiCurrentCard", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": { - "answer": "back content", - "question": "front content", - "deckName": "Default", - "modelName": "Basic", - "fieldOrder": 0, - "fields": { - "Front": {"value": "front content", "order": 0}, - "Back": {"value": "back content", "order": 1} - }, - "template": "Forward", - "cardId": 1498938915662, - "buttons": [1, 2, 3], - "nextReviews": ["<1m", "<10m", "4d"] - }, - "error": null - } - ``` - -* **guiStartCardTimer** - - Starts or resets the `timerStarted` value for the current card. This is useful for deferring the start time to when - it is displayed via the API, allowing the recorded time taken to answer the card to be more accurate when calling - `guiAnswerCard`. - - *Sample request*: - ```json - { - "action": "guiStartCardTimer", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **guiShowQuestion** - - Shows question text for the current card; returns `true` if in review mode or `false` otherwise. - - *Sample request*: - ```json - { - "action": "guiShowQuestion", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **guiShowAnswer** - - Shows answer text for the current card; returns `true` if in review mode or `false` otherwise. - - *Sample request*: - ```json - { - "action": "guiShowAnswer", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **guiAnswerCard** - - Answers the current card; returns `true` if succeeded or `false` otherwise. Note that the answer for the current - card must be displayed before before any answer can be accepted by Anki. - - *Sample request*: - ```json - { - "action": "guiAnswerCard", - "version": 6, - "params": { - "ease": 1 - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **guiDeckOverview** - - Opens the *Deck Overview* dialog for the deck with the given name; returns `true` if succeeded or `false` otherwise. - - *Sample request*: - ```json - { - "action": "guiDeckOverview", - "version": 6, - "params": { - "name": "Default" - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **guiDeckBrowser** - - Opens the *Deck Browser* dialog. - - *Sample request*: - ```json - { - "action": "guiDeckBrowser", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` - -* **guiDeckReview** - - Starts review for the deck with the given name; returns `true` if succeeded or `false` otherwise. - - *Sample request*: - ```json - { - "action": "guiDeckReview", - "version": 6, - "params": { - "name": "Default" - } - } - ``` - - *Sample result*: - ```json - { - "result": true, - "error": null - } - ``` - -* **guiExitAnki** - - Schedules a request to gracefully close Anki. This operation is asynchronous, so it will return immediately and - won't wait until the Anki process actually terminates. - - *Sample request*: - ```json - { - "action": "guiExitAnki", - "version": 6 - } - ``` - - *Sample result*: - ```json - { - "result": null, - "error": null - } - ``` +Documentation for currently supported actions is split up by category and is referenced below. Note that deprecated APIs +will continue to function despite not being listed on this page as long as your request is labeled with a version number +corresponding to when the API was available for use (**version 6** at the time of this writing). + +* [Cards](https://github.com/FooSoft/anki-connect/actions/cards.md) +* [Decks](https://github.com/FooSoft/anki-connect/actions/decks.md) +* [Graphical](https://github.com/FooSoft/anki-connect/actions/graphical.md) +* [Media](https://github.com/FooSoft/anki-connect/actions/media.md) +* [Miscellaneous](https://github.com/FooSoft/anki-connect/actions/miscellaneous.md) +* [Models](https://github.com/FooSoft/anki-connect/actions/models.md) +* [Notes](https://github.com/FooSoft/anki-connect/actions/notes.md) +* [Statistics](https://github.com/FooSoft/anki-connect/actions/statistics.md) diff --git a/actions/cards.md b/actions/cards.md new file mode 100644 index 0000000..9c2cc02 --- /dev/null +++ b/actions/cards.md @@ -0,0 +1,247 @@ +# Card Actions + +* **suspend** + + Suspend cards by card ID; returns `true` if successful (at least one card wasn't already suspended) or `false` + otherwise. + + *Sample request*: + ```json + { + "action": "suspend", + "version": 6, + "params": { + "cards": [1483959291685, 1483959293217] + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **unsuspend** + + Unsuspend cards by card ID; returns `true` if successful (at least one card was previously suspended) or `false` + otherwise. + + *Sample request*: + ```json + { + "action": "unsuspend", + "version": 6, + "params": { + "cards": [1483959291685, 1483959293217] + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **areSuspended** + + Returns an array indicating whether each of the given cards is suspended (in the same order). + + *Sample request*: + ```json + { + "action": "areSuspended", + "version": 6, + "params": { + "cards": [1483959291685, 1483959293217] + } + } + ``` + + *Sample result*: + ```json + { + "result": [false, true], + "error": null + } + ``` + +* **areDue** + + Returns an array indicating whether each of the given cards is due (in the same order). *Note*: cards in the + learning queue with a large interval (over 20 minutes) are treated as not due until the time of their interval has + passed, to match the way Anki treats them when reviewing. + + *Sample request*: + ```json + { + "action": "areDue", + "version": 6, + "params": { + "cards": [1483959291685, 1483959293217] + } + } + ``` + + *Sample result*: + ```json + { + "result": [false, true], + "error": null + } + ``` + +* **getIntervals** + + Returns an array of the most recent intervals for each given card ID, or a 2-dimensional array of all the intervals + for each given card ID when `complete` is `true`. Negative intervals are in seconds and positive intervals in days. + + *Sample request 1*: + ```json + { + "action": "getIntervals", + "version": 6, + "params": { + "cards": [1502298033753, 1502298036657] + } + } + ``` + + *Sample result 1*: + ```json + { + "result": [-14400, 3], + "error": null + } + ``` + + *Sample request 2*: + ```json + { + "action": "getIntervals", + "version": 6, + "params": { + "cards": [1502298033753, 1502298036657], + "complete": true + } + } + ``` + + *Sample result 2*: + ```json + { + "result": [ + [-120, -180, -240, -300, -360, -14400], + [-120, -180, -240, -300, -360, -14400, 1, 3] + ], + "error": null + } + ``` + +* **findCards** + + Returns an array of card IDs for a given query. Functionally identical to `guiBrowse` but doesn't use the GUI for + better performance. + + *Sample request*: + ```json + { + "action": "findCards", + "version": 6, + "params": { + "query": "deck:current" + } + } + ``` + + *Sample result*: + ```json + { + "result": [1494723142483, 1494703460437, 1494703479525], + "error": null + } + ``` + +* **cardsToNotes** + + Returns an unordered array of note IDs for the given card IDs. For cards with the same note, the ID is only given + once in the array. + + *Sample request*: + ```json + { + "action": "cardsToNotes", + "version": 6, + "params": { + "cards": [1502098034045, 1502098034048, 1502298033753] + } + } + ``` + + *Sample result*: + ```json + { + "result": [1502098029797, 1502298025183], + "error": null + } + ``` + +* **cardsInfo** + + Returns a list of objects containing for each card ID the card fields, front and back sides including CSS, note + type, the note that the card belongs to, and deck name, as well as ease and interval. + + *Sample request*: + ```json + { + "action": "cardsInfo", + "version": 6, + "params": { + "cards": [1498938915662, 1502098034048] + } + } + ``` + + *Sample result*: + ```json + { + "result": [ + { + "answer": "back content", + "question": "front content", + "deckName": "Default", + "modelName": "Basic", + "fieldOrder": 1, + "fields": { + "Front": {"value": "front content", "order": 0}, + "Back": {"value": "back content", "order": 1} + }, + "css":"p {font-family:Arial;}", + "cardId": 1498938915662, + "interval": 16, + "note":1502298033753 + }, + { + "answer": "back content", + "question": "front content", + "deckName": "Default", + "modelName": "Basic", + "fieldOrder": 0, + "fields": { + "Front": {"value": "front content", "order": 0}, + "Back": {"value": "back content", "order": 1} + }, + "css":"p {font-family:Arial;}", + "cardId": 1502098034048, + "interval": 23, + "note":1502298033753 + } + ], + "error": null + } + ``` diff --git a/actions/decks.md b/actions/decks.md new file mode 100644 index 0000000..fea9845 --- /dev/null +++ b/actions/decks.md @@ -0,0 +1,331 @@ +# Deck Actions + +* **deckNames** + + Gets the complete list of deck names for the current user. + + *Sample request*: + ```json + { + "action": "deckNames", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": ["Default"], + "error": null + } + ``` + +* **deckNamesAndIds** + + Gets the complete list of deck names and their respective IDs for the current user. + + *Sample request*: + ```json + { + "action": "deckNamesAndIds", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": {"Default": 1}, + "error": null + } + ``` + +* **getDecks** + + Accepts an array of card IDs and returns an object with each deck name as a key, and its value an array of the given + cards which belong to it. + + *Sample request*: + ```json + { + "action": "getDecks", + "version": 6, + "params": { + "cards": [1502298036657, 1502298033753, 1502032366472] + } + } + ``` + + *Sample result*: + ```json + { + "result": { + "Default": [1502032366472], + "Japanese::JLPT N3": [1502298036657, 1502298033753] + }, + "error": null + } + ``` + +* **createDeck** + + Create a new empty deck. Will not overwrite a deck that exists with the same name. + + *Sample request*: + ```json + { + "action": "createDeck", + "version": 6, + "params": { + "deck": "Japanese::Tokyo" + } + } + ``` + + *Sample result*: + ```json + { + "result": 1519323742721, + "error": null + } + ``` +* **changeDeck** + + Moves cards with the given IDs to a different deck, creating the deck if it doesn't exist yet. + + *Sample request*: + ```json + { + "action": "changeDeck", + "version": 6, + "params": { + "cards": [1502098034045, 1502098034048, 1502298033753], + "deck": "Japanese::JLPT N3" + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **deleteDecks** + + Deletes decks with the given names. If `cardsToo` is `true` (defaults to `false` if unspecified), the cards within + the deleted decks will also be deleted; otherwise they will be moved to the default deck. + + *Sample request*: + ```json + { + "action": "deleteDecks", + "version": 6, + "params": { + "decks": ["Japanese::JLPT N5", "Easy Spanish"], + "cardsToo": true + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **getDeckConfig** + + Gets the configuration group object for the given deck. + + *Sample request*: + ```json + { + "action": "getDeckConfig", + "version": 6, + "params": { + "deck": "Default" + } + } + ``` + + *Sample result*: + ```json + { + "result": { + "lapse": { + "leechFails": 8, + "delays": [10], + "minInt": 1, + "leechAction": 0, + "mult": 0 + }, + "dyn": false, + "autoplay": true, + "mod": 1502970872, + "id": 1, + "maxTaken": 60, + "new": { + "bury": true, + "order": 1, + "initialFactor": 2500, + "perDay": 20, + "delays": [1, 10], + "separate": true, + "ints": [1, 4, 7] + }, + "name": "Default", + "rev": { + "bury": true, + "ivlFct": 1, + "ease4": 1.3, + "maxIvl": 36500, + "perDay": 100, + "minSpace": 1, + "fuzz": 0.05 + }, + "timer": 0, + "replayq": true, + "usn": -1 + }, + "error": null + } + ``` + +* **saveDeckConfig** + + Saves the given configuration group, returning `true` on success or `false` if the ID of the configuration group is + invalid (such as when it does not exist). + + *Sample request*: + ```json + { + "action": "saveDeckConfig", + "version": 6, + "params": { + "config": { + "lapse": { + "leechFails": 8, + "delays": [10], + "minInt": 1, + "leechAction": 0, + "mult": 0 + }, + "dyn": false, + "autoplay": true, + "mod": 1502970872, + "id": 1, + "maxTaken": 60, + "new": { + "bury": true, + "order": 1, + "initialFactor": 2500, + "perDay": 20, + "delays": [1, 10], + "separate": true, + "ints": [1, 4, 7] + }, + "name": "Default", + "rev": { + "bury": true, + "ivlFct": 1, + "ease4": 1.3, + "maxIvl": 36500, + "perDay": 100, + "minSpace": 1, + "fuzz": 0.05 + }, + "timer": 0, + "replayq": true, + "usn": -1 + } + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **setDeckConfigId** + + Changes the configuration group for the given decks to the one with the given ID. Returns `true` on success or + `false` if the given configuration group or any of the given decks do not exist. + + *Sample request*: + ```json + { + "action": "setDeckConfigId", + "version": 6, + "params": { + "decks": ["Default"], + "configId": 1 + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **cloneDeckConfigId** + + Creates a new configuration group with the given name, cloning from the group with the given ID, or from the default + group if this is unspecified. Returns the ID of the new configuration group, or `false` if the specified group to + clone from does not exist. + + *Sample request*: + ```json + { + "action": "cloneDeckConfigId", + "version": 6, + "params": { + "name": "Copy of Default", + "cloneFrom": 1 + } + } + ``` + + *Sample result*: + ```json + { + "result": 1502972374573, + "error": null + } + ``` + +* **removeDeckConfigId** + + Removes the configuration group with the given ID, returning `true` if successful, or `false` if attempting to + remove either the default configuration group (ID = 1) or a configuration group that does not exist. + + *Sample request*: + ```json + { + "action": "removeDeckConfigId", + "version": 6, + "params": { + "configId": 1502972374573 + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` diff --git a/actions/graphical.md b/actions/graphical.md new file mode 100644 index 0000000..51db99e --- /dev/null +++ b/actions/graphical.md @@ -0,0 +1,274 @@ +# Graphical Actions + +* **guiBrowse** + + Invokes the *Card Browser* dialog and searches for a given query. Returns an array of identifiers of the cards that + were found. + + *Sample request*: + ```json + { + "action": "guiBrowse", + "version": 6, + "params": { + "query": "deck:current" + } + } + ``` + + *Sample result*: + ```json + { + "result": [1494723142483, 1494703460437, 1494703479525], + "error": null + } + ``` + +* **guiAddCards** + + Invokes the *Add Cards* dialog, presets the note using the given deck and model, with the provided field values and tags. + Invoking it multiple times closes the old window and _reopen the window_ with the new provided values. + + The `closeAfterAdding` member inside `options` group can be set to true to create a dialog that closes upon adding the note. + Invoking the action mutliple times with this option will create _multiple windows_. + + The result is the ID of the note which would be added, if the user chose to confirm the *Add Cards* dialogue. + + *Sample request*: + ```json + { + "action": "guiAddCards", + "version": 6, + "params": { + "note": { + "deckName": "Default", + "modelName": "Cloze", + "fields": { + "Text": "The capital of Romania is {{c1::Bucharest}}", + "Extra": "Romania is a country in Europe" + }, + "options": { + "closeAfterAdding": true + }, + "tags": [ + "countries" + ] + } + } + } + ``` + + *Sample result*: + ```json + { + "result": 1496198395707, + "error": null + } + ``` + +* **guiCurrentCard** + + Returns information about the current card or `null` if not in review mode. + + *Sample request*: + ```json + { + "action": "guiCurrentCard", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": { + "answer": "back content", + "question": "front content", + "deckName": "Default", + "modelName": "Basic", + "fieldOrder": 0, + "fields": { + "Front": {"value": "front content", "order": 0}, + "Back": {"value": "back content", "order": 1} + }, + "template": "Forward", + "cardId": 1498938915662, + "buttons": [1, 2, 3], + "nextReviews": ["<1m", "<10m", "4d"] + }, + "error": null + } + ``` + +* **guiStartCardTimer** + + Starts or resets the `timerStarted` value for the current card. This is useful for deferring the start time to when + it is displayed via the API, allowing the recorded time taken to answer the card to be more accurate when calling + `guiAnswerCard`. + + *Sample request*: + ```json + { + "action": "guiStartCardTimer", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **guiShowQuestion** + + Shows question text for the current card; returns `true` if in review mode or `false` otherwise. + + *Sample request*: + ```json + { + "action": "guiShowQuestion", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **guiShowAnswer** + + Shows answer text for the current card; returns `true` if in review mode or `false` otherwise. + + *Sample request*: + ```json + { + "action": "guiShowAnswer", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **guiAnswerCard** + + Answers the current card; returns `true` if succeeded or `false` otherwise. Note that the answer for the current + card must be displayed before before any answer can be accepted by Anki. + + *Sample request*: + ```json + { + "action": "guiAnswerCard", + "version": 6, + "params": { + "ease": 1 + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **guiDeckOverview** + + Opens the *Deck Overview* dialog for the deck with the given name; returns `true` if succeeded or `false` otherwise. + + *Sample request*: + ```json + { + "action": "guiDeckOverview", + "version": 6, + "params": { + "name": "Default" + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **guiDeckBrowser** + + Opens the *Deck Browser* dialog. + + *Sample request*: + ```json + { + "action": "guiDeckBrowser", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **guiDeckReview** + + Starts review for the deck with the given name; returns `true` if succeeded or `false` otherwise. + + *Sample request*: + ```json + { + "action": "guiDeckReview", + "version": 6, + "params": { + "name": "Default" + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **guiExitAnki** + + Schedules a request to gracefully close Anki. This operation is asynchronous, so it will return immediately and + won't wait until the Anki process actually terminates. + + *Sample request*: + ```json + { + "action": "guiExitAnki", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` diff --git a/actions/media.md b/actions/media.md new file mode 100644 index 0000000..8c534bd --- /dev/null +++ b/actions/media.md @@ -0,0 +1,99 @@ +# Media Actions + +* **storeMediaFile** + + Stores a file with the specified base64-encoded contents inside the media folder. alternatively you can specify a + url from where the file shell be downloaded. If both field `data` and `url` are provided, the `data` field will be + used. To prevent Anki from removing files not used by any cards (e.g. for configuration files), prefix the filename + with an underscore. These files are still synchronized to AnkiWeb. + + *Sample request*: + ```json + { + "action": "storeMediaFile", + "version": 6, + "params": { + "filename": "_hello.txt", + "data": "SGVsbG8sIHdvcmxkIQ==" + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + + *Content of `_hello.txt`*: + ``` + Hello world! + ``` + + *Sample request*: + ```json + { + "action": "storeMediaFile", + "version": 6, + "params": { + "filename": "_hello.txt", + "url": "https://url.to.file" + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **retrieveMediaFile** + + Retrieves the base64-encoded contents of the specified file, returning `false` if the file does not exist. + + *Sample request*: + ```json + { + "action": "retrieveMediaFile", + "version": 6, + "params": { + "filename": "_hello.txt" + } + } + ``` + + *Sample result*: + ```json + { + "result": "SGVsbG8sIHdvcmxkIQ==", + "error": null + } + ``` + +* **deleteMediaFile** + + Deletes the specified file inside the media folder. + + *Sample request*: + ```json + { + "action": "deleteMediaFile", + "version": 6, + "params": { + "filename": "_hello.txt" + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` diff --git a/actions/miscellaneous.md b/actions/miscellaneous.md new file mode 100644 index 0000000..3347067 --- /dev/null +++ b/actions/miscellaneous.md @@ -0,0 +1,170 @@ +# Miscellaneous Actions + +* **version** + + Gets the version of the API exposed by this plugin. Currently versions `1` through `6` are defined. + + This should be the first call you make to make sure that your application and AnkiConnect are able to communicate + properly with each other. New versions of AnkiConnect are backwards compatible; as long as you are using actions + which are available in the reported AnkiConnect version or earlier, everything should work fine. + + *Sample request*: + ```json + { + "action": "version", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": 6, + "error": null + } + ``` + +* **sync** + + Synchronizes the local Anki collections with AnkiWeb. + + *Sample request*: + ```json + { + "action": "sync", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **getProfiles** + + Retrieve the list of profiles. + + *Sample request*: + ```json + { + "action": "getProfiles", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": ["User 1"], + "error": null + } + ``` + +* **loadProfile** + + Selects the profile specified in request. + + *Sample request*: + ```json + { + "action": "loadProfile", + "params": { + "name": "user1" + }, + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **multi** + + Performs multiple actions in one request, returning an array with the response of each action (in the given order). + + *Sample request*: + ```json + { + "action": "multi", + "version": 6, + "params": { + "actions": [ + {"action": "deckNames"}, + { + "action": "browse", + "params": {"query": "deck:current"} + } + ] + } + } + ``` + + *Sample result*: + ```json + { + "result": [ + {"result": "Default", "error": null}, + {"result": [1494723142483, 1494703460437, 1494703479525], "error": null} + ], + "error": null + } + ``` + +* **exportPackage** + + Exports a given deck in `.apkg` format. Returns `true` if successful or `false` otherwise. The optional property + `includeSched` (default is `false`) can be specified to include the cards' scheduling data. + + *Sample request*: + ```json + { + "action": "exportPackage", + "version": 6, + "params": { + "deck": "Default", + "path": "/data/Deck.apkg", + "includeSched": true + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` + +* **importPackage** + + Imports a file in `.apkg` format into the collection. Returns `true` if successful or `false` otherwise. + Note that the file path is relative to Anki's collection.media folder, not to the client. + + *Sample request*: + ```json + { + "action": "importPackage", + "version": 6, + "params": { + "path": "/data/Deck.apkg" + } + } + ``` + + *Sample result*: + ```json + { + "result": true, + "error": null + } + ``` diff --git a/actions/models.md b/actions/models.md new file mode 100644 index 0000000..fcbcb43 --- /dev/null +++ b/actions/models.md @@ -0,0 +1,311 @@ +# Model Actions + +* **modelNames** + + Gets the complete list of model names for the current user. + + *Sample request*: + ```json + { + "action": "modelNames", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": ["Basic", "Basic (and reversed card)"], + "error": null + } + ``` + +* **modelNamesAndIds** + + Gets the complete list of model names and their corresponding IDs for the current user. + + *Sample request*: + ```json + { + "action": "modelNamesAndIds", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": { + "Basic": 1483883011648, + "Basic (and reversed card)": 1483883011644, + "Basic (optional reversed card)": 1483883011631, + "Cloze": 1483883011630 + }, + "error": null + } + ``` + +* **modelFieldNames** + + Gets the complete list of field names for the provided model name. + + *Sample request*: + ```json + { + "action": "modelFieldNames", + "version": 6, + "params": { + "modelName": "Basic" + } + } + ``` + + *Sample result*: + ```json + { + "result": ["Front", "Back"], + "error": null + } + ``` + +* **modelFieldsOnTemplates** + + Returns an object indicating the fields on the question and answer side of each card template for the given model + name. The question side is given first in each array. + + *Sample request*: + ```json + { + "action": "modelFieldsOnTemplates", + "version": 6, + "params": { + "modelName": "Basic (and reversed card)" + } + } + ``` + + *Sample result*: + ```json + { + "result": { + "Card 1": [["Front"], ["Back"]], + "Card 2": [["Back"], ["Front"]] + }, + "error": null + } + ``` + + +* **createModel** + + Creates a new model to be used in Anki. User must provide the `modelName`, `inOrderFields` and `cardTemplates` to be + used in the model. Optionally the `Name` field can be provided for each entry of `cardTemplates`. By default the + card names will be `Card 1`, `Card 2`, and so on. + + *Sample request* + ```json + { + "action": "createModel", + "version": 6, + "params": { + "modelName": "newModelName", + "inOrderFields": ["Field1", "Field2", "Field3"], + "css": "Optional CSS with default to builtin css", + "cardTemplates": [ + { + "Name": "My Card 1", + "Front": "Front html {{Field1}}", + "Back": "Back html {{Field2}}" + } + ] + } + } + ``` + + *Sample result* + ```json + { + "result":{ + "sortf":0, + "did":1, + "latexPre":"\\documentclass[12pt]{article}\n\\special{papersize=3in,5in}\n\\usepackage[utf8]{inputenc}\n\\usepackage{amssymb,amsmath}\n\\pagestyle{empty}\n\\setlength{\\parindent}{0in}\n\\begin{document}\n", + "latexPost":"\\end{document}", + "mod":1551462107, + "usn":-1, + "vers":[ + + ], + "type":0, + "css":".card {\n font-family: arial;\n font-size: 20px;\n text-align: center;\n color: black;\n background-color: white;\n}\n", + "name":"TestApiModel", + "flds":[ + { + "name":"Field1", + "ord":0, + "sticky":false, + "rtl":false, + "font":"Arial", + "size":20, + "media":[ + + ] + }, + { + "name":"Field2", + "ord":1, + "sticky":false, + "rtl":false, + "font":"Arial", + "size":20, + "media":[ + + ] + } + ], + "tmpls":[ + { + "name":"My Card 1", + "ord":0, + "qfmt":"", + "afmt":"This is the back of the card {{Field2}}", + "did":null, + "bqfmt":"", + "bafmt":"" + } + ], + "tags":[ + + ], + "id":"1551462107104", + "req":[ + [ + 0, + "none", + [ + + ] + ] + ] + }, + "error":null + } + ``` + + +* **modelTemplates** + + Returns an object indicating the template content for each card connected to the provided model by name. + + *Sample request*: + ```json + { + "action": "modelTemplates", + "version": 6, + "params": { + "modelName": "Basic (and reversed card)" + } + } + ``` + + *Sample result* + ```json + { + "result": { + "Card 1": { + "Front": "{{Front}}", + "Back": "{{FrontSide}}\n\n
\n\n{{Back}}" + }, + "Card 2": { + "Front": "{{Back}}", + "Back": "{{FrontSide}}\n\n
\n\n{{Front}}" + } + }, + "error": null + } + ``` + + +* **modelStyling** + + Gets the CSS styling for the provided model by name. + + *Sample request*: + ```json + { + "action": "modelStyling", + "version": 6, + "params": { + "modelName": "Basic (and reversed card)" + } + } + ``` + + *Sample result* + ```json + { + "result": { + "css": ".card {\n font-family: arial;\n font-size: 20px;\n text-align: center;\n color: black;\n background-color: white;\n}\n" + }, + "error": null + } + ``` + + +* **updateModelTemplates** + + Modify the templates of an existing model by name. Only specifies cards and specified sides will be modified. + If an existing card or side is not included in the request, it will be left unchanged. + + *Sample request*: + ```json + { + "action": "updateModelTemplates", + "version": 6, + "params": { + "model": { + "name": "Custom", + "templates": { + "Card 1": { + "Front": "{{Question}}?", + "Back": "{{Answer}}!" + } + } + } + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + + +* **updateModelStyling** + + Modify the CSS styling of an existing model by name. + + *Sample request*: + ```json + { + "action": "updateModelStyling", + "version": 6, + "params": { + "model": { + "name": "Custom", + "css": "p { color: blue; }" + } + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` diff --git a/actions/notes.md b/actions/notes.md new file mode 100644 index 0000000..7985b43 --- /dev/null +++ b/actions/notes.md @@ -0,0 +1,325 @@ +# Note Actions + +* **addNote** + + Creates a note using the given deck and model, with the provided field values and tags. Returns the identifier of + the created note created on success, and `null` on failure. + + AnkiConnect can download audio files and embed them in newly created notes. The corresponding `audio` note member is + optional and can be omitted. If you choose to include it, it should contain a single object or an array of objects + with mandatory `url` and `filename` fields. The `skipHash` field can be optionally provided to skip the inclusion of + downloaded files with an MD5 hash that matches the provided value. This is useful for avoiding the saving of error + pages and stub files. The `fields` member is a list of fields that should play audio when the card is displayed in + Anki. The `allowDuplicate` member inside `options` group can be set to true to enable adding duplicate cards. + Normally duplicate cards can not be added and trigger exception. The `duplicateScope` member inside `options` can be + used to specify the scope for which duplicates are checked. A value of `"deck"` will only check for duplicates in the + target deck; any other value will check the entire collection. + + *Sample request*: + ```json + { + "action": "addNote", + "version": 6, + "params": { + "note": { + "deckName": "Default", + "modelName": "Basic", + "fields": { + "Front": "front content", + "Back": "back content" + }, + "options": { + "allowDuplicate": false, + "duplicateScope": "deck" + }, + "tags": [ + "yomichan" + ], + "audio": [{ + "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ", + "filename": "yomichan_ねこ_猫.mp3", + "skipHash": "7e2c2f954ef6051373ba916f000168dc", + "fields": [ + "Front" + ] + }] + } + } + } + ``` + + *Sample result*: + ```json + { + "result": 1496198395707, + "error": null + } + ``` + +* **addNotes** + + Creates multiple notes using the given deck and model, with the provided field values and tags. Returns an array of + identifiers of the created notes (notes that could not be created will have a `null` identifier). Please see the + documentation for `addNote` for an explanation of objects in the `notes` array. + + *Sample request*: + ```json + { + "action": "addNotes", + "version": 6, + "params": { + "notes": [ + { + "deckName": "Default", + "modelName": "Basic", + "fields": { + "Front": "front content", + "Back": "back content" + }, + "tags": [ + "yomichan" + ], + "audio": [{ + "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ", + "filename": "yomichan_ねこ_猫.mp3", + "skipHash": "7e2c2f954ef6051373ba916f000168dc", + "fields": [ + "Front" + ] + }] + } + ] + } + } + ``` + + *Sample result*: + ```json + { + "result": [1496198395707, null], + "error": null + } + ``` + +* **canAddNotes** + + Accepts an array of objects which define parameters for candidate notes (see `addNote`) and returns an array of + booleans indicating whether or not the parameters at the corresponding index could be used to create a new note. + + *Sample request*: + ```json + { + "action": "canAddNotes", + "version": 6, + "params": { + "notes": [ + { + "deckName": "Default", + "modelName": "Basic", + "fields": { + "Front": "front content", + "Back": "back content" + }, + "tags": [ + "yomichan" + ] + } + ] + } + } + ``` + + *Sample result*: + ```json + { + "result": [true], + "error": null + } + ``` + +* **updateNoteFields** + + Modify the fields of an exist note. You can also include audio files which will be added to the note with an + optional `audio` property. Please see the documentation for `addNote` for an explanation of objects in the `audio` array. + + *Sample request*: + ```json + { + "action": "updateNoteFields", + "version": 6, + "params": { + "note": { + "id": 1514547547030, + "fields": { + "Front": "new front content", + "Back": "new back content" + }, + "audio": [{ + "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ", + "filename": "yomichan_ねこ_猫.mp3", + "skipHash": "7e2c2f954ef6051373ba916f000168dc", + "fields": [ + "Front" + ] + }] + } + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **addTags** + + Adds tags to notes by note ID. + + *Sample request*: + ```json + { + "action": "addTags", + "version": 6, + "params": { + "notes": [1483959289817, 1483959291695], + "tags": "european-languages" + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **removeTags** + + Remove tags from notes by note ID. + + *Sample request*: + ```json + { + "action": "removeTags", + "version": 6, + "params": { + "notes": [1483959289817, 1483959291695], + "tags": "european-languages" + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` + +* **getTags** + + Gets the complete list of tags for the current user. + + *Sample request*: + ```json + { + "action": "getTags", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": ["european-languages", "idioms"], + "error": null + } + ``` + +* **findNotes** + + Returns an array of note IDs for a given query. Same query syntax as `guiBrowse`. + + *Sample request*: + ```json + { + "action": "findNotes", + "version": 6, + "params": { + "query": "deck:current" + } + } + ``` + + *Sample result*: + ```json + { + "result": [1483959289817, 1483959291695], + "error": null + } + ``` + +* **notesInfo** + + Returns a list of objects containing for each note ID the note fields, tags, note type and the cards belonging to + the note. + + *Sample request*: + ```json + { + "action": "notesInfo", + "version": 6, + "params": { + "notes": [1502298033753] + } + } + ``` + + *Sample result*: + ```json + { + "result": [ + { + "noteId":1502298033753, + "modelName": "Basic", + "tags":["tag","another_tag"], + "fields": { + "Front": {"value": "front content", "order": 0}, + "Back": {"value": "back content", "order": 1} + } + } + ], + "error": null + } + ``` + + +* **deleteNotes** + + Deletes notes with the given ids. If a note has several cards associated with it, all associated cards will be deleted. + + *Sample request*: + ```json + { + "action": "deleteNotes", + "version": 6, + "params": { + "notes": [1502298033753] + } + } + ``` + + *Sample result*: + ```json + { + "result": null, + "error": null + } + ``` diff --git a/actions/statistics.md b/actions/statistics.md new file mode 100644 index 0000000..b116d0c --- /dev/null +++ b/actions/statistics.md @@ -0,0 +1,44 @@ +# Statistic Actions + +* **getNumCardsReviewedToday** + + Gets the count of cards that have been reviewed in the current day (with day start time as configured by user in anki) + + *Sample request*: + ```json + { + "action": "getNumCardsReviewedToday", + "version": 6 + } + ``` + + *Sample result*: + ```json + { + "result": 0, + "error": null + } + ``` + +* **getCollectionStatsHTML** + + Gets the collection statistics report + + *Sample request*: + ```json + { + "action": "getCollectionStatsHTML", + "version": 6, + "params": { + "wholeCollection": true + } + } + ``` + + *Sample result*: + ```json + { + "error": null, + "result": "
lots of HTML here
" + } + ```