diff --git a/README.md b/README.md index 8c3d94a..0836655 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,22 @@ curl localhost:8765 -X POST -d '{"action": "version"}' Below is a list of currently supported actions. Requests with invalid actions or parameters will a return `null` result. +Categories: + +* [Miscellaneous](#miscellaneous) +* [Decks](#decks) +* [Deck Configurations](#deck-configurations) +* [Models](#models) +* [Note Creation](#note-creation) +* [Note Tags](#note-tags) +* [Card Suspension](#card-suspension) +* [Card Intervals](#card-intervals) +* [Finding Notes and Cards](#finding-notes-and-cards) +* [File Storage](#file-storage) +* [Graphical](#graphical) + +### Miscellaneous ### + * **version** Gets the version of the API exposed by this plugin. Currently versions `1` through `4` are defined. @@ -104,6 +120,24 @@ Below is a list of currently supported actions. Requests with invalid actions or 4 ``` +* **upgrade** + + Displays a confirmation dialog box in Anki asking the user if they wish to upgrade AnkiConnect to the latest version + from the project's [master branch](https://raw.githubusercontent.com/FooSoft/anki-connect/master/AnkiConnect.py) on + GitHub. Returns a boolean value indicating if the plugin was upgraded or not. + + *Sample request*: + ``` + { + "action": "upgrade" + } + ``` + + *Sample response*: + ``` + true + ``` + * **multi** Performs multiple actions in one request, returning an array with the response of each action (in the given order). @@ -132,74 +166,7 @@ Below is a list of currently supported actions. Requests with invalid actions or ] ``` -* **storeFile** - - Stores a file with the specified base64-encoded contents inside the media folder. Returns `true` upon success or - `false` if attempting to write a file outside the media folder. - - Note: 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*: - ``` - { - "action": "storeFile", - "params": { - "filename": "_hello.txt", - "data": "SGVsbG8sIHdvcmxkIQ==" - } - } - ``` - - *Sample response*: - ``` - true - ``` - - *Content of `_hello.txt`*: - ``` - Hello world! - ``` - -* **retrieveFile** - - Retrieves the base64-encoded contents of the specified file, returning `false` if the file does not exist or if - attempting to read a file outside the media folder. - - *Sample request*: - ``` - { - "action": "retrieveFile", - "params": { - "filename": "_hello.txt" - } - } - ``` - - *Sample response*: - ``` - "SGVsbG8sIHdvcmxkIQ==" - ``` - -* **deleteFile** - - Deletes the specified file inside the media folder, returning `true` if successful, or `false` if the file does not - exist or if attempting to delete a file outside the media folder. - - *Sample request*: - ``` - { - "action": "deleteFile", - "params": { - "filename": "_hello.txt" - } - } - ``` - - *Sample response*: - ``` - true - ``` +### Decks ### * **deckNames** @@ -237,47 +204,72 @@ Below is a list of currently supported actions. Requests with invalid actions or } ``` -* **modelNames** +* **getDecks** - Gets the complete list of model names for the current user. + 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*: ``` { - "action": "modelNames" - } - ``` - - *Sample response*: - ``` - [ - "Basic", - "Basic (and reversed card)" - ] - ``` - -* **modelFieldNames** - - Gets the complete list of field names for the provided model name. - - *Sample request*: - ``` - { - "action": "modelFieldNames", + "action": "getDecks", "params": { - "modelName": "Basic" + "cards": [1502298036657, 1502298033753, 1502032366472] } } ``` *Sample response*: ``` - [ - "Front", - "Back" - ] + { + "Default": [1502032366472], + "Japanese::JLPT N3": [1502298036657, 1502298033753] + } ``` +* **changeDeck** + + Moves cards with the given IDs to a different deck, creating the deck if it doesn't exist yet. + + *Sample request*: + ``` + { + "action": "changeDeck", + "params": { + "cards": [1502098034045, 1502098034048, 1502298033753], + "deck": "Japanese::JLPT N3" + } + } + ``` + + *Sample response*: + ``` + 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*: + ``` + { + "action": "deleteDecks", + "params": { + "decks": ["Japanese::JLPT N5", "Easy Spanish"], + "cardsToo": true + } + } + ``` + + *Sample response*: + ``` + null + ``` + +### Deck Configurations ### + * **getDeckConfig** Gets the config group object for the given deck. @@ -415,6 +407,51 @@ Below is a list of currently supported actions. Requests with invalid actions or true ``` +### Models ### + +* **modelNames** + + Gets the complete list of model names for the current user. + + *Sample request*: + ``` + { + "action": "modelNames" + } + ``` + + *Sample response*: + ``` + [ + "Basic", + "Basic (and reversed card)" + ] + ``` + +* **modelFieldNames** + + Gets the complete list of field names for the provided model name. + + *Sample request*: + ``` + { + "action": "modelFieldNames", + "params": { + "modelName": "Basic" + } + } + ``` + + *Sample response*: + ``` + [ + "Front", + "Back" + ] + ``` + +### Note Creation ### + * **addNote** Creates a note using the given deck and model, with the provided field values and tags. Returns the identifier of @@ -530,6 +567,8 @@ Below is a list of currently supported actions. Requests with invalid actions or ] ``` +### Note Tags ### + * **addTags** Adds tags to notes by note ID. @@ -570,6 +609,8 @@ Below is a list of currently supported actions. Requests with invalid actions or null ``` +### Card Suspension ### + * **suspend** Suspend cards by card ID; returns `true` if successful (at least one card wasn't already suspended) or `false` @@ -629,6 +670,8 @@ Below is a list of currently supported actions. Requests with invalid actions or [false, true] ``` +### Card Intervals ### + * **areDue** Returns an array indicating whether each of the given cards is due (in the same order). Note: cards in the learning @@ -689,6 +732,7 @@ Below is a list of currently supported actions. Requests with invalid actions or ] ``` +### Finding Notes and Cards ### * **findNotes** @@ -736,71 +780,6 @@ Below is a list of currently supported actions. Requests with invalid actions or ] ``` -* **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*: - ``` - { - "action": "getDecks", - "params": { - "cards": [1502298036657, 1502298033753, 1502032366472] - } - } - ``` - - *Sample response*: - ``` - { - "Default": [1502032366472], - "Japanese::JLPT N3": [1502298036657, 1502298033753] - } - ``` - - -* **changeDeck** - - Moves cards with the given IDs to a different deck, creating the deck if it doesn't exist yet. - - *Sample request*: - ``` - { - "action": "changeDeck", - "params": { - "cards": [1502098034045, 1502098034048, 1502298033753], - "deck": "Japanese::JLPT N3" - } - } - ``` - - *Sample response*: - ``` - 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*: - ``` - { - "action": "deleteDecks", - "params": { - "decks": ["Japanese::JLPT N5", "Easy Spanish"], - "cardsToo": true - } - } - ``` - - *Sample response*: - ``` - null - ``` - * **cardsToNotes** Returns an (unordered) array of note IDs for the given card IDs. For cards with the same note, the ID is only @@ -824,6 +803,79 @@ Below is a list of currently supported actions. Requests with invalid actions or ] ``` +### File Storage ### + +* **storeFile** + + Stores a file with the specified base64-encoded contents inside the media folder. Returns `true` upon success or + `false` if attempting to write a file outside the media folder. + + Note: 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*: + ``` + { + "action": "storeFile", + "params": { + "filename": "_hello.txt", + "data": "SGVsbG8sIHdvcmxkIQ==" + } + } + ``` + + *Sample response*: + ``` + true + ``` + + *Content of `_hello.txt`*: + ``` + Hello world! + ``` + +* **retrieveFile** + + Retrieves the base64-encoded contents of the specified file, returning `false` if the file does not exist or if + attempting to read a file outside the media folder. + + *Sample request*: + ``` + { + "action": "retrieveFile", + "params": { + "filename": "_hello.txt" + } + } + ``` + + *Sample response*: + ``` + "SGVsbG8sIHdvcmxkIQ==" + ``` + +* **deleteFile** + + Deletes the specified file inside the media folder, returning `true` if successful, or `false` if the file does not + exist or if attempting to delete a file outside the media folder. + + *Sample request*: + ``` + { + "action": "deleteFile", + "params": { + "filename": "_hello.txt" + } + } + ``` + + *Sample response*: + ``` + true + ``` + +### Graphical ### + * **guiBrowse** Invokes the card browser and searches for a given query. Returns an array of identifiers of the cards that were found. @@ -1019,24 +1071,6 @@ Below is a list of currently supported actions. Requests with invalid actions or true ``` -* **upgrade** - - Displays a confirmation dialog box in Anki asking the user if they wish to upgrade AnkiConnect to the latest version - from the project's [master branch](https://raw.githubusercontent.com/FooSoft/anki-connect/master/AnkiConnect.py) on - GitHub. Returns a boolean value indicating if the plugin was upgraded or not. - - *Sample request*: - ``` - { - "action": "upgrade" - } - ``` - - *Sample response*: - ``` - true - ``` - ## License ## This program is free software: you can redistribute it and/or modify