anki-connect/actions/notes.md
David Sauerwein 7ef10e92da
Allow to add media to notes by file path or base64 encoded data (#230)
* Allow to add media to notes by file path or base64 encoded data

* Adjust Media Actions documentation

* Adjust Note Actions documentation
2021-02-20 10:04:25 -08:00

12 KiB

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, video, and picture files and embed them in newly created notes. The corresponding audio, video, and picture note members are optional and can be omitted. If you choose to include any of them, they should contain a single object or an array of objects with the mandatory filename field and one of data, path or url. Refer to the documentation of storeMediaFile for an explanation of these fields. The skipHash field can be optionally provided to skip the inclusion of 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 or video, or show a picture 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 "deckName" will only check for duplicates in the target deck; any other value will check the entire collection. The duplicateScopeOptions object can be used to specify some additional settings. duplicateScopeOptions.deckName will specify which deck to use for checking duplicates in. If undefined or null, the target deck will be used. duplicateScopeOptions.checkChildren will change whether or not duplicate cards are checked in child decks; the default value is false.

    Sample request:

    {
        "action": "addNote",
        "version": 6,
        "params": {
            "note": {
                "deckName": "Default",
                "modelName": "Basic",
                "fields": {
                    "Front": "front content",
                    "Back": "back content"
                },
                "options": {
                    "allowDuplicate": false,
                    "duplicateScope": "deck",
                    "duplicateScopeOptions": {
                        "deckName": "Default",
                        "checkChildren": false
                    }
                },
                "tags": [
                    "yomichan"
                ],
                "audio": [{
                    "url": "https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ",
                    "filename": "yomichan_ねこ_猫.mp3",
                    "skipHash": "7e2c2f954ef6051373ba916f000168dc",
                    "fields": [
                        "Front"
                    ]
                }],
                "video": [{
                    "url": "https://cdn.videvo.net/videvo_files/video/free/2015-06/small_watermarked/Contador_Glam_preview.mp4",
                    "filename": "countdown.mp4",
                    "skipHash": "4117e8aab0d37534d9c8eac362388bbe",
                    "fields": [
                        "Back"
                    ]
                }],
                "picture": [{
                    "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c7/A_black_cat_named_Tilly.jpg/220px-A_black_cat_named_Tilly.jpg",
                    "filename": "black_cat.jpg",
                    "skipHash": "8d6e4646dfae812bf39651b59d7429ce",
                    "fields": [
                        "Back"
                    ]
                }]
            }
        }
    }
    

    Sample result:

    {
        "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:

    {
        "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"
                        ]
                    }],
                    "video": [{
                        "url": "https://cdn.videvo.net/videvo_files/video/free/2015-06/small_watermarked/Contador_Glam_preview.mp4",
                        "filename": "countdown.mp4",
                        "skipHash": "4117e8aab0d37534d9c8eac362388bbe",
                        "fields": [
                            "Back"
                        ]
                    }],
                    "picture": [{
                        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c7/A_black_cat_named_Tilly.jpg/220px-A_black_cat_named_Tilly.jpg",
                        "filename": "black_cat.jpg",
                        "skipHash": "8d6e4646dfae812bf39651b59d7429ce",
                        "fields": [
                            "Back"
                        ]
                    }]
                }
            ]
        }
    }
    

    Sample result:

    {
        "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:

    {
        "action": "canAddNotes",
        "version": 6,
        "params": {
            "notes": [
                {
                    "deckName": "Default",
                    "modelName": "Basic",
                    "fields": {
                        "Front": "front content",
                        "Back": "back content"
                    },
                    "tags": [
                        "yomichan"
                    ]
                }
            ]
        }
    }
    

    Sample result:

    {
        "result": [true],
        "error": null
    }
    
  • updateNoteFields

    Modify the fields of an exist note. You can also include audio, video, or picture files which will be added to the note with an optional audio, video, or picture property. Please see the documentation for addNote for an explanation of objects in the audio, video, or picture array.

    Sample request:

    {
        "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:

    {
        "result": null,
        "error": null
    }
    
  • addTags

    Adds tags to notes by note ID.

    Sample request:

    {
        "action": "addTags",
        "version": 6,
        "params": {
            "notes": [1483959289817, 1483959291695],
            "tags": "european-languages"
        }
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }
    
  • removeTags

    Remove tags from notes by note ID.

    Sample request:

    {
        "action": "removeTags",
        "version": 6,
        "params": {
            "notes": [1483959289817, 1483959291695],
            "tags": "european-languages"
        }
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }
    
  • getTags

    Gets the complete list of tags for the current user.

    Sample request:

    {
        "action": "getTags",
        "version": 6
    }
    

    Sample result:

    {
        "result": ["european-languages", "idioms"],
        "error": null
    }
    
  • clearUnusedTags

    Clears all the unused tags in the notes for the current user.

    Sample request:

    {
        "action": "clearUnusedTags",
        "version": 6
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }
    
  • replaceTags

    Replace tags in notes by note ID.

    Sample request:

    {
        "action": "replaceTags",
        "version": 6,
        "params": {
            "notes": [1483959289817, 1483959291695],
            "tag_to_replace": "european-languages",
            "replace_with_tag": "french-languages"
        }
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }
    
  • replaceTagsInAllNotes

    Replace tags in all the notes for the current user.

    Sample request:

    {
        "action": "replaceTagsInAllCards",
        "version": 6,
        "params": {
            "tag_to_replace": "european-languages",
            "replace_with_tag": "french-languages"
        }
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }
    
  • findNotes

    Returns an array of note IDs for a given query. Query syntax is documented here.

    Sample request:

    {
        "action": "findNotes",
        "version": 6,
        "params": {
            "query": "deck:current"
        }
    }
    

    Sample result:

    {
        "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:

    {
        "action": "notesInfo",
        "version": 6,
        "params": {
            "notes": [1502298033753]
        }
    }
    

    Sample result:

    {
        "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:

    {
        "action": "deleteNotes",
        "version": 6,
        "params": {
            "notes": [1502298033753]
        }
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }
    
  • removeEmptyNotes

    Removes all the empty notes for the current user.

    Sample request:

    {
        "action": "removeEmptyNotes",
        "version": 6
    }
    

    Sample result:

    {
        "result": null,
        "error": null
    }